home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / doc / chap08.doc < prev    next >
Text File  |  1994-08-18  |  155KB  |  3,867 lines
  1. dice/CommandSummary                                      dice/CommandSummary
  2.  
  3.         Command, Purpose
  4.  
  5.         a68k, Freeware 68000 assembler (Charlie Gibbs)
  6.  
  7.         autorefs, Generate a quick-ref file from autodocs/.H files for DME
  8.  
  9.         ci, Check in RCS Source
  10.  
  11.         co, Check out RCS Source
  12.  
  13.         cat, Type a file or files (takes wild cards)
  14.  
  15.         das, DICE Assembler
  16.  
  17.         dc1, DICE Compiler
  18.  
  19.         dcc, DICE Compiler Front End
  20.  
  21.         dcpp, DICE Preprocessor
  22.  
  23.         diff, File Compare Utility
  24.  
  25.         dlink, DICE Linker
  26.  
  27.         dmake, Make Utility
  28.  
  29.         dme, Editor
  30.  
  31.         dobj, Disassembles objects
  32.  
  33.         dprof, Profiler
  34.  
  35.         dsearch, Search for a String in a File
  36.  
  37.         du, Determine Disk Space Usage
  38.  
  39.         dupdate, Distribution Maker
  40.  
  41.         enforcer, Locate Hidden bugs in Programs (MMU)
  42.  
  43.         expand, Expand Wild cards to stdout with formatting
  44.  
  45.         fdtolib, Creates Link Libraries from .FD Files
  46.  
  47.         flush, Flush Memory
  48.  
  49.         head, Display Start of a File
  50.  
  51.         ident, Identify Files
  52.  
  53.         istrip, Strip Comments from Include Files
  54.  
  55.         lbmake, Link Library Creation Utility
  56.  
  57.         lharc, Archive Utility
  58.  
  59.         libmake, Link Library Creation Utility
  60.  
  61.         libtos, Convert Large-Data 1.3/2.0 Amiga.lib to Small-Data
  62.  
  63.         loadabs, Absolute Locator
  64.  
  65.         makeproto, Create Prototype Header File
  66.  
  67.         merge, Three Way File Merge
  68.  
  69.         rcs, Change RCS File Attributes
  70.  
  71.         rcsclean, Clean up RCS Working Files
  72.  
  73.         rcsdiff, Compare RCS Revisions
  74.  
  75.         rcsmerge, Merge RCS Revisions
  76.  
  77.         rlog, Display RCS History
  78.  
  79.         romable, Generate Romable Image
  80.  
  81.         touch, Update the File Datestamp
  82.  
  83.         wc, Count Elements in a File
  84.  
  85.  
  86. dice/a68k                                                          dice/a68k
  87.  
  88.     NAME
  89.         Freeware 68000 assembler (Charlie Gibbs)
  90.  
  91.     SYNOPSIS
  92.         A68K [ options ] sourcefile
  93.  
  94.     DESCRIPTION
  95.         A68k is a Freeware 68000 assembler.
  96.  
  97.  -d[[!]prefix]
  98.             What does this option do?
  99.  
  100.  -e[equate file]
  101.             What does this option do?
  102.  
  103.         -f  What does this option do?
  104.  
  105.         -g  What does this option do?
  106.  
  107.  -hheader file
  108.             What does this option do?
  109.  
  110.  -iinclude dirlist
  111.             What does this option do?
  112.  
  113.         -k  What does this option do?
  114.  
  115.  -l[listing file]
  116.             Specify Listing FIle
  117.  
  118.  -msmall data offset
  119.             What does this option do?
  120.  
  121.         -n  What does this option do?
  122.  
  123.  -oobject file
  124.             What does this option do?
  125.  
  126.  -ppage depth
  127.             What does this option do?
  128.  
  129.  -q[quiet interval]
  130.             What does this option do?
  131.  
  132.         -s  What does this option do?
  133.  
  134.         -t  What does this option do?
  135.  
  136.  -w[hash size][,heap size]
  137.             Heap size default:  -w2047,1024
  138.  
  139.         -x  What does this option do?
  140.  
  141.         -y  What does this option do?
  142.  
  143.  -z[debug start][,debug end]
  144.             What does this option do?
  145.  
  146.     SEE ALSO
  147.         das
  148.  
  149.  
  150. dice/autorefs                                                  dice/autorefs
  151.  
  152.     NAME
  153.         Generate DME quick reference file
  154.  
  155.     SYNOPSIS
  156.         AUTOREFS outfile docfile docfile ...
  157.  
  158.     DESCRIPTION
  159.         Autorefs creates a DME reference file from the specified document
  160.         files.  AmigaDOS wildcards may be used to specify the doc files.
  161.  
  162.    outfile  The output file is generally specified as DME.REFS and placed in
  163.             the same directory as the documents it references.  A path to this
  164.             directory is normally created via the ADDPATH command from DME's
  165.             startup script S:.EDRC.
  166.  
  167.    docfile  The output file to be appended to.
  168.  
  169.     SEE ALSO
  170.         dme
  171.  
  172.  
  173. dice/ci                                                              dice/ci
  174.  
  175.     NAME
  176.         Check in RCS Source
  177.  
  178.     SYNOPSIS
  179.         ci [ options ] file ...
  180.  
  181.     DESCRIPTION
  182.         Ci stores new revisions into RCS files.  Each file name ending in `,v'
  183.         is taken to be an RCS file, all others are assumed to be working files
  184.         containing new revisions.  Ci deposits the contents of each working
  185.         file into the corresponding RCS file.  If only a working file is
  186.         given, ci tries to find the corresponding RCS file in the directory
  187.         RCS and then in the current directory.  For more details, see the file
  188.         naming section below.
  189.  
  190.         For ci to work, the caller's login must be on the access list, except
  191.         if the access list is empty or the caller is the superuser or the
  192.         owner of the file.  To append a new revision to an existing branch,
  193.         the tip revision on that branch must be locked by the caller.
  194.         Otherwise, only a new branch can be created.  This restriction is not
  195.         enforced for the owner of the file, unless locking is set to strict
  196.         (see rcs).  A lock held by someone else may be broken with the rcs
  197.         command.
  198.  
  199.         Normally, ci checks whether the revision to be deposited is different
  200.         from the preceding one.  If it is not different, ci either aborts the
  201.         deposit (if -q is given) or asks whether to abort (if -q is omitted). 
  202.         A deposit can be forced with the -f option.
  203.  
  204.         For each revision deposited, ci prompts for a log message.  The log
  205.         message should summarize the change and must be terminated with a line
  206.         containing a single `.' or a control-D.  If several files are checked
  207.         in, ci asks whether to reuse the previous log message.  If the
  208.         standard input is not a terminal, ci suppresses the prompt and uses
  209.         the same log message for all files.  See also -m.
  210.  
  211.         The number of the deposited revision can be given by any of the
  212.         options -r, -f, -k, -l, -u, or -q.
  213.  
  214.         If the RCS file does not exist, ci creates it and deposits the
  215.         contents of the working file as the initial revision (default number:
  216.         1.1).  The access list is initialized to empty.  Instead of the log
  217.         message, ci requests descriptive text (see -t below).
  218.  
  219.    -r[rev]  assigns the revision number rev to the checked-in revision,
  220.             releases the corresponding lock, and deletes the working file. 
  221.             This is the default.  Rev may be symbolic, numeric, or mixed.
  222.  
  223.             If rev is a revision number, it must be higher than the latest one
  224.             on the branch to which rev belongs, or must start a new branch.
  225.  
  226.             If rev is a branch rather than a revision number, the new revision
  227.             is appended to that branch.  The level number is obtained by
  228.             incrementing the tip revision number of that branch.  If rev
  229.             indicates a non-existing branch, that branch is created with the
  230.             initial revision numbered rev.1.
  231.  
  232.             If rev is omitted, ci tries to derive the new revision number from
  233.             the caller's last lock.  If the caller has locked the tip revision
  234.             of a branch, the new revision is appended to that branch.  The new
  235.             revision number is obtained by incrementing the tip revision
  236.             number.  If the caller locked a non-tip revision, a new branch is
  237.             started at that revision by incrementing the highest branch number
  238.             at that revision.  The default initial branch and level numbers
  239.             are 1.
  240.  
  241.             If rev is omitted and the caller has no lock, but he is the owner
  242.             of the file and locking is not set to strict, then the revision is
  243.             appended to the default branch (normally the trunk; see the -b
  244.             option of rcs).
  245.  
  246.             :: NOTE: On the trunk, revisions can be appended to the end, but
  247.             :: not inserted.
  248.  
  249.    -f[rev]  forces a deposit; the new revision is deposited even it is not
  250.             different from the preceding one.
  251.  
  252.    -k[rev]  searches the working file for keyword values to determine its
  253.             revision number, creation date, state, and author (see co), and
  254.             assigns these values to the deposited revision, rather than
  255.             computing them locally.  It also generates a default login message
  256.             noting the login of the caller and the actual checkin date.  This
  257.             option is useful for software distribution. A revision that is
  258.             sent to several sites should be checked in with the -k option at
  259.             these sites to preserve the original number, date, author, and
  260.             state.  The extracted keyword values and the default log message
  261.             may be overridden with the options -r, -d, -s, -w, and -m.
  262.  
  263.    -l[rev]  works like -r, except it performs an additional co -l for the
  264.             deposited revision.  Thus, the deposited revision is immediately
  265.             checked out again and locked.  This is useful for saving a
  266.             revision although one wants to continue editing it after the
  267.             checkin.
  268.  
  269.    -u[rev]  works like -l, except that the deposited revision is not locked. 
  270.             This is useful if one wants to process (e.g., compile) the
  271.             revision immediately after checkin.
  272.  
  273.    -q[rev]  quiet mode; diagnostic output is not printed.  A revision that is
  274.             not different from the preceding one is not deposited, unless -f
  275.             is given.
  276.  
  277.     -ddate  uses date for the checkin date and time.  Date may be specified in
  278.             free format as explained in co.  Useful for lying about the
  279.             checkin date, and for -k if no date is available.
  280.  
  281.      -mmsg  uses the string msg as the log message for all revisions checked
  282.             in.
  283.  
  284.     -nname  assigns the symbolic name name to the number of the checked-in
  285.             revision.  Ci prints an error message if name is already assigned
  286.             to another number.
  287.  
  288.     -Nname  same as -n, except that it overrides a previous assignment of
  289.             name.
  290.  
  291.    -sstate  sets the state of the checked-in revision to the identifier state.
  292.             The default is Exp.
  293.  
  294.  -t[txtfile]
  295.             writes descriptive text into the RCS file (deletes the existing
  296.             text).  If txtfile is omitted, ci prompts the user for text
  297.             supplied from the standard input, terminated with a line
  298.             containing a single `.' or control-D.  Otherwise, the descriptive
  299.             text is copied from the file txtfile.  During initialization,
  300.             descriptive text is requested even if -t is not given.  The prompt
  301.             is suppressed if standard input is not a terminal.
  302.  
  303.    -wlogin  uses login for the author field of the deposited revision.  Useful
  304.             for lying about the author, and for -k if no author is available.
  305.  
  306.     FILE NAMING
  307.         Pairs of RCS files and working files may be specified in 3 ways (see
  308.         also the example section of co).
  309.  
  310.         0) Both the RCS file and the working file are given.  The RCS file
  311.         0) name is of the form path1/workfile,v and the working file name is
  312.         0) of the form path2/workfile, where path1/ and path2/ are (possibly
  313.         0) different or empty) paths and workfile is a file name.
  314.  
  315.         1) Only the RCS file is given.  Then the working file is assumed to be
  316.         1) in the current directory and its name is derived from the name of
  317.         1) the RCS file by removing path1/ and the suffix ,v.
  318.  
  319.         2) Only the working file is given.  Then ci looks for an RCS file of
  320.         2) the form path2/RCS/workfile,v or path2/workfile,v (in this order).
  321.  
  322.         If the RCS file is specified without a path in 1) and 2), then co
  323.         looks for the RCS file first in the directory RCS, then in the
  324.         directory contained in the file RCS_LINK, followed by the current
  325.         directory.
  326.  
  327.     DIAGNOSTICS
  328.         For each revision, ci prints the RCS file, the working file, and the
  329.         number of both the deposited and the preceding revision.  The exit
  330.         status always refers to the last file checked in, and is 0 if the
  331.         operation was successful, 1 otherwise.
  332.  
  333.     SEE ALSO
  334.         co, ident, rcs, rcsdiff, rcsintro, rcsmerge, rlog
  335.  
  336.  
  337. dice/co                                                              dice/co
  338.  
  339.     NAME
  340.         Check out RCS Source
  341.  
  342.     SYNOPSIS
  343.         co [ options ] file ...
  344.  
  345.     DESCRIPTION
  346.         Co retrieves a revision from each RCS file and stores it into the
  347.         corresponding working file.  Each file name ending in `,v' is taken to
  348.         be an RCS file; all other files are assumed to be working files.  If
  349.         only a working file is given, co tries to find the corresponding file
  350.         in the RCS directory and then in the current directory.  For more
  351.         details, see the file naming section below.
  352.  
  353.         Revisions of an RCS file may be checked out locked or unlocked.
  354.         Locking a revision prevents overlapping updates.  A revision checked
  355.         out for reading or processing (e.g., compiling) need not be locked.  A
  356.         revision checked out for editing and later checkin must normally be
  357.         locked.  Co with locking fails if the revision to be checked out is
  358.         currently locked by another user.  (A lock may be broken with the rcs
  359.         command.)  Co with locking also requires the caller to be on the
  360.         access list of the RCS file, unless he is the owner of the file or the
  361.         superuser, or the access list is empty.  Co without locking is not
  362.         subject to accesslist restrictions, and is not affected by the
  363.         presence of locks.
  364.  
  365.         A revision is selected by options for revision or branch number,
  366.         checkin date/time, author, or state.  When the selection options are
  367.         applied in combination, co retrieves the latest revision that
  368.         satisfies all of them.  If none of the selection options is specified,
  369.         co retrieves the latest revision on the default branch (normally the
  370.         trunk, see the -b option of rcs).  A revision or branch number may be
  371.         attached to any of the options -f, -l, -p, -q, -r, or -u. The options
  372.         -d (date), -s (state), and -w (author) retrieve from a single branch,
  373.         the selected branch, which is either specified by one of -f,..., -u,
  374.         or the default branch.
  375.  
  376.         A co command applied to an RCS file with no revisions creates a
  377.         zero-length working file.  co always performs keyword substitution
  378.         (see below).
  379.  
  380.    -r[rev]  retrieves the latest revision whose number is less than or equal
  381.             to rev.      If rev indicates a branch rather than a revision, the
  382.             latest revision on that branch is retrieved.  If rev is omitted,
  383.             the latest revision on the default branch (see the -b option of
  384.             rcs) is retrieved. rev is composed of one or more numeric or
  385.             symbolic fields separated by `.'.  The numeric equivalent of a
  386.             symbolic field is specified with the -n option of the commands ci
  387.             and rcs.
  388.  
  389.    -l[rev]  same as -r, except that it also locks the retrieved revision for
  390.             the caller.  See option -r for handling of the revision number
  391.             rev.
  392.  
  393.    -u[rev]  same as -r, except that it unlocks the retrieved revision (if it
  394.             was locked by the caller).  If rev is omitted, -u retrieves the
  395.             latest revision locked by the caller; if no such lock exists, it
  396.             retrieves the latest revision on the default branch.
  397.  
  398.    -f[rev]  forces the overwriting of the working file; useful in connection
  399.             with -q.  See also the section on file modes below.
  400.  
  401.    -p[rev]  prints the retrieved revision on the standard output rather than
  402.             storing it in the working file.  This option is useful when co is
  403.             part of a pipe.
  404.  
  405.    -q[rev]  quiet mode; diagnostics are not printed.
  406.  
  407.     -ddate  retrieves the latest revision on the selected branch whose checkin
  408.             date/time is less than or equal to date.  The date and time may be
  409.             given in free format and are converted to local time.  Examples of
  410.             formats for date:
  411.  
  412.             22-April-1982
  413.             17:20-CDT
  414.             2:25 AM
  415.             Dec.  29, 1983
  416.             Tue-PDT, 1981
  417.             4pm Jul 21 (free format)
  418.             Fri, April 16 15:52:25 EST 1982 (output of ctime).
  419.  
  420.             Most fields in the date and time may be defaulted.  co determines
  421.             the defaults in the order year, month, day, hour, minute, and
  422.             second (most to least significant).  At least one of these fields
  423.             must be provided.  For omitted fields that are of higher
  424.             significance than the highest provided field, the current values
  425.             are assumed.  For all other omitted fields, the lowest possible
  426.             values are assumed.  For example, the date "20, 10:30" defaults to
  427.             10:30:00 of the 20th of the current month and current year.  The
  428.             date/time must be quoted if it contains spaces.
  429.  
  430.    -sstate  retrieves the latest revision on the selected branch whose state
  431.             is set to state.
  432.  
  433.  -w[login]  retrieves the latest revision on the selected branch which was
  434.             checked in by the user with login name login.  If the argument
  435.             login is omitted, the caller's login is assumed.
  436.  
  437.  -jjoinlist
  438.             generates a new revision which is the join of the revisions on
  439.             joinlist. Joinlist is a comma-separated list of pairs of the form
  440.             rev2:rev3, where rev2 and rev3 are (symbolic or numeric) revision
  441.             numbers. For the initial such pair, rev1 denotes the revision
  442.             selected by the above options -r, ..., -w.  For all other pairs,
  443.             rev1 denotes the revision generated by the previous pair.  (Thus,
  444.             the output of one join becomes the input to the next.)
  445.  
  446.             For each pair, co joins revisions rev1 and rev3 with respect to
  447.             rev2.  This means that all changes that transform rev2 into rev1
  448.             are applied to a copy of rev3.  This is particularly useful if
  449.             rev1 and rev3 are the ends of two branches that have rev2 as a
  450.             common ancestor.  If rev1 < rev2 < rev3 on the same branch,
  451.             joining generates a new revision which is like rev3, but with all
  452.             changes that lead from rev1 to rev2 undone.  If changes from rev2
  453.             to rev1 overlap with changes from rev2 to rev3, co prints a
  454.             warning and includes the overlapping sections, delimited by the
  455.             lines
  456.  
  457.             <<<<<<<
  458.             rev1
  459.             =======
  460.             rev3
  461.             >>>>>>>
  462.  
  463.             For the initial pair, rev2 may be omitted.  The default is the
  464.             common ancestor.  If any of the arguments indicate branches, the
  465.             latest revisions on those branches are assumed.  The options -l
  466.             and -u lock or unlock rev1.
  467.  
  468.     KEYWORD
  469.     SUBSTITUTION
  470.         Strings of the form $keyword$ and $keyword:...$ embedded in the text
  471.         are replaced with strings of the form $keyword: value $, where keyword
  472.         and value are pairs listed below.  Keywords may be embedded in literal
  473.         strings or comments to identify a revision.
  474.  
  475.         Initially, the user enters strings of the form $keyword$.  On
  476.         checkout, co replaces these strings with strings of the form 
  477.         $keyword: value$. If a revision containing strings of the latter form
  478.         is checked back in, the value fields will be replaced during the next
  479.         checkout.  Thus, the keyword values are automatically updated on
  480.         checkout.
  481.  
  482.         Keyword, Value
  483.  
  484.         $Author: dice $, The login name of the user who checked in the
  485.         revision.
  486.  
  487.         $Date: 1994/08/18 05:37:03 $, The date and time the revision was checked
  488.         in.
  489.  
  490.         $Header: Work:Devel/oi/diceman/RCS/chap08.txt,v 1.2 92/06/09 06:40:43
  491.         jtoebes Exp $, A standard header containing the full pathname of the
  492.         RCS file,, the revision number,, the date,, the author,, the state,,
  493.         and the locker (if locked).
  494.  
  495.         $Id: chap08.doc,v 30.8 1994/08/18 05:37:03 dice Exp dice $, Same as
  496.         $Header: Work:Devel/oi/diceman/RCS/chap08.txt,v 1.2 92/06/09 06:40:43
  497.         jtoebes Exp $,, except that the RCS file name is without a path.
  498.  
  499.         $Locker: dice $, The login name of the user who locked the revision (empty
  500.         if not locked).
  501.  
  502.         $Log: chap08.doc,v $
  503. # Revision 30.8  1994/08/18  05:37:03  dice
  504. # .
  505. #
  506. # Revision 30.0  1994/06/10  17:54:37  dice
  507. # .
  508. #
  509. # Revision 30.0  1994/06/10  17:54:37  dice
  510. # .
  511. # Revision 1.2  92/06/09  06:40:43  jtoebes
  512.         Incorporate new das, enforcer examples from Bryce.  Fix up dprof
  513.         example section.
  514.  
  515.         Revision 1.1  92/06/01  23:01:29  jtoebes Initial revision , The log
  516.         message supplied during checkin,, preceded by a header containing the
  517.         RCS file name,, the revision number,, the author,, and the date. 
  518.         Existing log messages are NOT replaced.  Instead,, the new log message
  519.         is inserted after $Log: chap08.doc,v $
  520. # Revision 30.8  1994/08/18  05:37:03  dice
  521. # .
  522. #
  523. # Revision 30.0  1994/06/10  17:54:37  dice
  524. # .
  525. #
  526. # Revision 30.0  1994/06/10  17:54:37  dice
  527. # .
  528. # Revision 1.2  92/06/09 
  529.         06:40:43  jtoebes Incorporate new das, enforcer examples from Bryce. 
  530.         Fix up dprof example section.
  531.  
  532.         Revision 1.1  92/06/01  23:01:29  jtoebes Initial revision .  This is
  533.         useful for accumulating a complete change log in a source file.
  534.  
  535.         $RCSfile: chap08.doc,v $, The name of the RCS file without path.
  536.  
  537.         $Revision: 30.8 $, The revision number assigned to the revision.
  538.  
  539.         $Source: /home/dice/com/doc/RCS/chap08.doc,v $, The full pathname
  540.         of the RCS file.
  541.  
  542.         $State: Exp $, The state assigned to the revision with the -s option
  543.         of rcs or ci.
  544.  
  545.     FILE NAMING
  546.         Pairs of RCS files and working files may be specified in 3 ways (see
  547.         also the example section).
  548.  
  549.         3) Both the RCS file and the working file are given.  The RCS file
  550.         3) name is of the form path1/workfile,v and the working file name is
  551.         3) of the form path2/workfile, where path1/ and path2/ are (possibly
  552.         3) different or empty) paths and workfile is a file name.
  553.  
  554.         4) Only the RCS file is given.  Then the working file is created in
  555.         4) the current directory and its name is derived from the name of the
  556.         4) RCS file by removing path1/ and the suffix ,v.
  557.  
  558.         5) Only the working file is given.  Then co looks for an RCS file of
  559.         5) the form path2/RCS/workfile,v or path2/workfile,v (in this order).
  560.  
  561.         If the RCS file is specified without a path in 1) and 2), then co
  562.         looks for the RCS file first in the directory RCS, then in the
  563.         directory contained in the file RCS_LINK, followed by the current
  564.         directory.
  565.  
  566.     EXAMPLES
  567.         Suppose the current directory contains a subdirectory RCS with an RCS
  568.         file io.c,v.  Then all of the following commands retrieve the latest
  569.         revision from RCS/io.c,v and store it into io.c.
  570.  
  571.         co io.c
  572.         co RCS/io.c,v
  573.         co io.c,v
  574.         co io.c RCS/io.c,v
  575.         co io.c io.c,v
  576.         co RCS/io.c,v io.c
  577.         co io.c,v io.c
  578.  
  579.     FILE MODES
  580.         If a file with the name of the working file exists already and has
  581.         write permission, co aborts the checkout if -q is given, or asks
  582.         whether to abort if -q is not given.  If the existing working file is
  583.         not writable or -f is given, the working file is deleted without
  584.         asking.
  585.  
  586.     DIAGNOSTICS
  587.         The RCS file name, the working file name, and the revision number
  588.         retrieved are written to the diagnostic output.  The exit status
  589.         always refers to the last file checked out, and is 0 if the operation
  590.         was successful, 1 otherwise.
  591.  
  592.     SEE ALSO
  593.         ci, ident, rcs, rcsdiff, rcsintro, rcsmerge, rlog
  594.  
  595.     LIMITATIONS
  596.         The option -d gets confused in some circumstances, and accepts no date
  597.         before 1970.  There is no way to suppress the expansion of keywords,
  598.         except by writing them differently.
  599.  
  600.     BUGS
  601.         The option -j does not work for files that contain lines with a single
  602.         `.'.
  603.  
  604.  
  605. dice/cat                                                            dice/cat
  606.  
  607.     NAME
  608.         Display file contents
  609.  
  610.     SYNOPSIS
  611.         cat [file ...]
  612.  
  613.     DESCRIPTION
  614.         Cat displays one or more files on the standard output.
  615.  
  616.       file  Specifies the files to be displayed.  Wild cards are accepted.
  617.  
  618.  
  619. dice/das                                                            dice/das
  620.  
  621.     NAME
  622.         DICE Assembler
  623.  
  624.     SYNOPSIS
  625.         DAS asmfile [-o objectfile] [-E errorfile] [-nu]
  626.  
  627.     DESCRIPTION
  628.         Das is a minimal 68000 assembler designed to assemble the output of
  629.         dc1.
  630.  
  631.         :: NOTE: Das should not be used for assembly projects, it is meant
  632.         :: solely to deal with the output from the compiler.  Das supports
  633.         :: only a minimal subset of features.
  634.  
  635.  -o objfile
  636.             Specify object file, else writes to asmfile.o.
  637.  
  638.  -E errorfile
  639.             Specify file for errors, else diagnostics are sent to stderr.
  640.  
  641.        -nu  Specify that HUNK_UNIT hunks have no name.  This option is used
  642.             for creating link libraries, to make the library smaller)
  643.  
  644.     SEE ALSO
  645.         a68k, Chapter 9
  646.  
  647.  
  648. dice/dc1                                                            dice/dc1
  649.  
  650.     NAME
  651.         DICE Compiler
  652.  
  653.     SYNOPSIS
  654.         DC1 cppd_src_file [-o outfile] options
  655.  
  656.     DESCRIPTION
  657.         DC1 is the compiler itself.  As input it requires an already
  658.         preprocessed file and as output it produces assembly.  Many assemblers
  659.         will not be able to assemble the output due to forward referenced REG
  660.         labels and the PROCSTART, PROCEND directives.  The output is normally
  661.         fed to DAS which generates the object file
  662.  
  663.         The compiler generates absolute-data references and absolute code
  664.         references by default.  Do not confuse this with DCC's default, which
  665.         is small-data and small-code.
  666.  
  667.         The compiler will put argument and auto variables into registers
  668.         according to register availability and usage.  It will use A0-A1/D0-D1
  669.         for register variables whenever possible.  Consequently, the most
  670.         heavily used variables will be in registers even for very large
  671.         subroutines.
  672.  
  673.         You should get into the habit of using auto declarations within sub
  674.         blocks rather than declare all your autos at the top of the procedure.
  675.         Apart from making the code more modular, this will enable the compiler
  676.         to make better decisions when allocating register variables.
  677.  
  678.         DCC does not do any major contents tracking and redundant instructions
  679.         will be generated.  DAS will handle properly optimizing branches and
  680.         DAS will eventually have a peephole optimizer built in it to handle
  681.         other obvious redundancies.
  682.  
  683.         The compiler does other optimizations itself, such as using bit
  684.         instructions to handle special cases of &, |, and ^, include using
  685.         BTST.
  686.  
  687.         :: NOTE: volatile forces a data item NOT to be placed in a register. 
  688.         :: register is currently ignored.  const is ignored by default but
  689.         :: will force objects into the code section given the -ms or -mS
  690.         :: options (see below). Other type and storage qualifiers are
  691.         :: described in chapter 5.
  692.  
  693.    -S
  694.     -S0  Set alternate section names libdata and libbss
  695.  
  696.   -Sd name  Set section name for data sections
  697.  
  698.   -Sb name  Set section name for bss sections
  699.  
  700.   -Sc name  Set section name for code sections
  701.  
  702.   -SD name  Set section name for __far data sections
  703.  
  704.   -SB name  Set section name for __far bss sections
  705.  
  706.             The -S option allows you to modify the default section naming
  707.             conventions.  DICE uses data, text, and bss as defaults for the
  708.             data, code, and bss sections.
  709.  
  710.             The DICE c.lib is compiled with -S and the startup code (c.o)
  711.             references these first to force c.lib's data to come before
  712.             program data.  The data ordering is then as follows:
  713.  
  714.         6) Library Initialized Data
  715.  
  716.         7) Program Initialized Data
  717.  
  718.         8) Library BSS Space
  719.  
  720.         9) Program BSS Space
  721.  
  722.         As long as the program does not declare more than 64KBytes of
  723.         initialized data it can be linked with the small-data model c.lib. 
  724.         Thus, large-data-model programs that declare more than 64KBytes of BSS
  725.         space will still link with the small-data-model c.lib
  726.  
  727.         This may be of no consequence because any __far declared data will be
  728.         placed in a different data segment entirely.  Simply declare your
  729.         large arrays as __far and the rest may remain small-data
  730.  
  731.      -d[#]  Set debug mode.  This isn't pretty, it is primarily used for
  732.             diagnosing potential compiler problems.
  733.  
  734.    -E file  specify stderr file, any errors are appended to the file instead
  735.             of to stdout. Useful for batch compiles
  736.  
  737.         -R  Tells the compile to remove (delete) the input file when it no
  738.             longer needs it.  The input file is usually a temporary
  739.             preprocessor file and DCC will use this option to get DC1 to
  740.             delete it as soon as possible.
  741.  
  742.     -proto  The main compiler will generate errors for any unprototyped
  743.             function call.
  744.  
  745.         -r  Resident option.  The main compiler will generate special autoinit
  746.             code to initialize data-data relocations.  This simplifies the
  747.             work that DLink and the startup module must do to support
  748.             residentable programs.
  749.  
  750.         -v  Verbose
  751.  
  752.  -o outfile
  753.             Specify assembly output file name
  754.  
  755.        -mc  Small-code model (DCC default)
  756.  
  757.        -mC  Large-code model (DC1 default)
  758.  
  759.        -md  Small-data model (DCC default)
  760.  
  761.        -mD  Large-data model (DC1 default)
  762.  
  763.        -mw  Absolute-word addressing (overides -md/-mD)
  764.  
  765.        -ma  Absolute addressing (no effect on DC1 operation)
  766.  
  767.             These options specify the memory model.  The small-code model uses
  768.             PC-relative addressing and the small-data model uses A4-relative
  769.             addressing
  770.  
  771.             -mw is used when making ROMable code and specifies that the
  772.             ABSOLUTE WORD addressing mode be used instead of either absolute
  773.             long or A4-relative.  Absolute word addresses are resolved at link
  774.             time.
  775.  
  776.             :: NOTE: This option should not be used when generating
  777.             :: executables meant to run on the Amiga.
  778.  
  779.       -ms0  (default) const is ignored
  780.  
  781.        -ms  string constants and const objs placed in code section
  782.  
  783.        -mS  string constants and const objs placed in code section
  784.  
  785.             These options control how const data items are handled, including
  786.             string constants such as char *ptr = "abcd"; The default is to
  787.             ignore the const type qualifier.
  788.  
  789.             If -ms is specified string constants and const data items are
  790.             placed in the code section.  Local references to const data items
  791.             use PC-RELATIVE addressing.  Remote references (from other
  792.             modules) to const data items use ABSOLUTE LONG addressing.
  793.  
  794.             -mS works the same as -ms but remote references are forced to use
  795.             PC-RELATIVE addressing.
  796.  
  797.             :: NOTE: This can be dangerous and the final CODE size MUST BE
  798.             :: LESS THAN 32KBYTES!
  799.  
  800.             Usually it is safe to use -ms and, in fact, can save a lot of
  801.             memory when combined with -r residentable programs because the
  802.             string constants will not be duplicated for each running instance
  803.             of the program.
  804.  
  805.     SEE ALSO
  806.         dcc, dcpp, dlink
  807.  
  808.  
  809. dice/dcc                                                            dice/dcc
  810.  
  811.     NAME
  812.         DICE Compiler Front End
  813.  
  814.     SYNOPSIS
  815.         dcc options file file ...
  816.  
  817.     DESCRIPTION
  818.         Dcc is similar to the UNIX cc command and is the frontend for the DICE
  819.         compiler.
  820.  
  821.         Options may occur anywhere on the command line but MUST occur singly.
  822.         That is, -c -a instead of -ca.  file arguments to options may occur
  823.         with or without an intervening space.  -oFILE and -o FILE are both
  824.         legal.
  825.  
  826.         Files ending in .a or .asm are assumed to be assembly files.  Files
  827.         ending in .l or .lib are assumed to be library files.  Files ending in
  828.         .o or .obj are assumed to be object files.  All other files are
  829.         assumed to be C source files.
  830.  
  831.         Normally DCC compiles all C source files, assembles all asm files, and
  832.         links the resulting object files with any specified .o files together
  833.         to produce an executable.  The output file may optionally be specified
  834.         with the -o option.  If not specified, a default output filename based
  835.         on the name of the input file is generated.  This general action is
  836.         modified by two options:
  837.  
  838.         -c  DCC does NOT link, -o specifies the output object file
  839.  
  840.         -a  DCC does NOT assemble (i.e.  leaves the .a file resulting from a
  841.             compile).  -o specifies the output assembly file
  842.  
  843.             If neither option is given -o specifies the name of the resulting
  844.             executable.
  845.  
  846.             The default object directory is T: and may be changed with the -O
  847.             option.  The default temporary directory is also T: and may be
  848.             changed with the -T option.  IF YOU HAVE LIMITED MEMORY you may
  849.             have to specify that temporary files not be placed in T: either by
  850.             re-assigning T: or using the -T option.  DICE goes much slower if
  851.             temporary files must be written to a floppy or even a hard disk.
  852.  
  853.             || WARNING: asm files are assembled with DAS, See the assembler
  854.             || reference if you intend to assemble non-DC1 generated assembly
  855.  
  856.       file  File to compile, assemble (.a), and/or link (.o, .lib)
  857.  
  858.      @file  containing further list of files, one per line.  (blank lines and
  859.             lines beginning with ';' or '#' are ignored.  File may NOT contain
  860.             further options).
  861.  
  862.    -E file  specify stderr file, any errors are appended to file instead of to
  863.             stdout.  Useful for batch compiles
  864.  
  865.         -c  Compile C source files and assemble into OBJECT files only (do not
  866.             link).
  867.  
  868.         -a  Compile C source files into ASSEMBLY files (do not assemble or
  869.             link).
  870.  
  871.             Keep in mind the DAS will do further optimizations on the assembly
  872.             file that you see.
  873.  
  874.        -l0  Do not link default libraries (dlib:c.lib dlib:amigas.lib
  875.             dlib:auto.lib), or standard startup (dlib:c.o and dlib:x.o).
  876.  
  877.             «» Beginner's Note: Do not use this option
  878.  
  879.             This option is used in special circumstances, such as when
  880.             generating .libraries or .devices.
  881.  
  882.             || WARNING: Dice is much more dependant on its startup code (c.o
  883.             || and x.o) than other compilers, do not link without the startup
  884.             || unless you know what you are doing.
  885.  
  886.     -l lib  When linking include this library.  (space is optional)
  887.  
  888.             Generally -l is used to include the math library (-lm) when
  889.             formatted floating point *printf()s are required.
  890.  
  891.             See Chapter 5 for more information on linking in custom libraries.
  892.  
  893.       -2.0  Default amiga.lib is dlib:amigas20.lib. Default amiga include path
  894.             is dinclude:amiga20/
  895.  
  896.       -2.x  where x is the second digit replacing the 0 in the above example. 
  897.             This option is useful when compiling for different versions of the
  898.             operating system.
  899.  
  900.       -1.3  Like -2.0, but using dlib:amigas13.lib and dinclude:amiga13/
  901.  
  902.       -1.x  Like -2.x, this allows for a specific operating system version
  903.             include files.
  904.  
  905.        -L0  remove default library search path, including all explicitly
  906.             specified (-L dir) directories up to this point.
  907.  
  908.     -L dir  add the specified directory to the library search path.  If the
  909.             object module or library can not be found in the current
  910.             directory, directories specified with -L are searched.  -L
  911.             directories are searched before the default library directory
  912.             (DLIB:), assuming it was not removed with -L0 .
  913.  
  914.             Note that the directory path specified by -L is used to search for
  915.             libraries AND object modules.
  916.  
  917.             A trailing '/' is optional
  918.  
  919.        -I0  Remove default include path from search list.  The default include
  920.             path is dinclude: and dinclude:amiga/ (unless modified by -1.x and
  921.             -2.x options)
  922.  
  923.     -I dir  When compiling scan this include directory (space is optional) The
  924.             specified path takes precedence over defaults but defaults are NOT
  925.             removed.
  926.  
  927.  -D define[=value]
  928.             Pre-define a symbol
  929.  
  930.         -U  Undefine __STDC__, mc68000, _DCC, and AMIGA.
  931.  
  932.             «» Beginner's Note: Do not use any of these options
  933.  
  934.  -Houtfile=hdrfile
  935.             This option enables precompiled header file generation and
  936.             operation. You may specify any number of -H options.  Example
  937.             usage:
  938.  
  939.             -Ht:defs.m=defs.h
  940.  
  941.             When DICE encounters an #include <defs.h> this will cause it to
  942.             first check for the existance of T:DEFS.M ...  if T:DEFS.M does
  943.             not exist DICE will generate it from <defs.h>.  if T:DEFS.M does
  944.             exist then DICE will use it directly and ignore <defs.h>
  945.  
  946.             You must specify the -H option both to have DICE create the
  947.             precompiled header file and to have DICE use the precompiled
  948.             header file.  Normally one makes operation as transparent as
  949.             possible so as not depend on the option existing when porting to
  950.             other enviroments.
  951.  
  952.             ## DANGER: A precompiled header file contains the preprocessed
  953.             ## header and preprocessor macros.  These are set in stone!
  954.  
  955.             If you modify a #define that would normally effect preprocessing
  956.             of a header file which is precompiled THE EFFECT WILL NOT OCCUR. 
  957.             It is strongly suggested you use precompiled headers ONLY with
  958.             includes that are pretty much unchanging.  For example, the
  959.             commodore includes or otherwise have an appropriate dependancy in
  960.             your DMakefile or make script to delete the precompiled header
  961.             file whenever any of your headers are modified.
  962.  
  963.             Normally one has a single -H option that enables precompiling of a
  964.             local header file, say defs.h, which contains #include's of all
  965.             other header files.  Source modules would then #include <defs.h>
  966.  
  967.             «» Beginners's Note: Do not use this option
  968.  
  969.    -o file  Specify output executable, object, or assembly file name depending
  970.             on what you are producing.  The space is optional
  971.  
  972.       -020  Generate code for the 68020 and later microprocessors
  973.  
  974.       -030  Generate code for the 68030 and later microprocessors
  975.  
  976.       -881  Generate inline FFP code for the 68881
  977.  
  978.       -882  Generate inline FFP code for the 68882
  979.  
  980.             «» Beginner's NOTE: Do not use any of these options
  981.  
  982.             These options exist to produce 020 and 030 opcodes, and 881/882
  983.             inline assembly for floating point operations.
  984.  
  985.        -md  small data model (default) uses A4-relative
  986.  
  987.        -mD  large data model uses absolute-long
  988.  
  989.        -mc  small code model (default) uses PC-relative
  990.  
  991.        -mC  large code model uses absolute-long
  992.  
  993.             «» Beginner's Note: Use only -mD if you declare more than 64KBytes
  994.             «» of data.
  995.  
  996.             These options specify the default data and code model to use.  The
  997.             model may be overriden by use of the __near and __far type
  998.             qualifiers on a variable by variable basis.
  999.  
  1000.             DICE defaults to the small data and small code model, and is able
  1001.             to generate >32KBytes of code using the small code model so you
  1002.             should never have to use -mC.  Note that the DICE libraries have
  1003.             all been compiled with the small-data model, and certain
  1004.             applications may disrupt the base register, A4...  in this case
  1005.             use of the __geta4 type qualifier should be of use.  If worse
  1006.             comes to worse you can recompile a large-data model c.lib, but I
  1007.             suggest you try other solutions first.
  1008.  
  1009.       -ms0  (default), Only const objects are put into a CODE hunk
  1010.  
  1011.        -ms  String constants are put into the read-only code hunk
  1012.  
  1013.        -mS  String constants are put into the read-only code hunk AND all
  1014.             external const references use NEAR addressing
  1015.  
  1016.             «» Beginner's Note: Use only -ms
  1017.  
  1018.             -ms0 turns off -ms/-mS in case you have it in your DCCOPTS
  1019.             enviroment variable and want to turn it off.
  1020.  
  1021.             Default operation (no -ms or -mS) puts const items into a
  1022.             read-only CODE hunk.  Locally declared objects are referenced
  1023.             using PC-REL while external objects (declared in some other
  1024.             module) are referenced using 32-BIT ABSOLUTE addressing.
  1025.  
  1026.             -ms will additionally make all string constants, such as "fubar",
  1027.             const and referenced via PC-REL.  -ms is an extremely useful
  1028.             option when you will never modify any of your string constants
  1029.             because the strings are not copied for multiple running instances
  1030.             of the program (if resident).
  1031.  
  1032.             -mS works like -ms, but in addition forces all external const
  1033.             references to use PC-REL addressing INSTEAD of 32-bit absolute
  1034.             addressing.
  1035.  
  1036.             :: Note: This is a very dangerous option, do not use unless the
  1037.             :: final code size is less than 32 kbytes.
  1038.  
  1039.             Using -ms along with -r can result in huge savings of memory due
  1040.             to the string constants being moved out of the data segment (which
  1041.             must be duplicated for each running instance of the program).
  1042.  
  1043.             || WARNING: In all cases if you declare an object as const it must
  1044.             || be extern'd as const in other modules or incorrect code will be
  1045.             || generated.  This is true whether you use -ms/S or not.
  1046.  
  1047.        -mr  registered arguments, light
  1048.  
  1049.        -mR  registered arguments, medium
  1050.  
  1051.       -mRR  registered arguments, strict
  1052.  
  1053.             «» Beginner's Note: Either do not use these options or use only
  1054.             «» -mr
  1055.  
  1056.             These options control the automatic registerization of procedure
  1057.             arguments.  Only those prototyped procedures declaring 4 or fewer
  1058.             arguments will be registered.  Values are passed in D0/D1/A0/A1
  1059.             according to the type of variable and availabilty of registers.
  1060.  
  1061.             -mr generates entry points for both the registered argument and
  1062.             normal version of the function.  This option is ideal for
  1063.             generating multi-model libraries.
  1064.  
  1065.             -mR generates only a single, registered entry point
  1066.  
  1067.             -mRR is similar to -mR but extends registerization to indirect
  1068.             function calls (that are fully prototyped).  This is the most
  1069.             dangerous option.
  1070.  
  1071.             Note that -mr and -mR assign the normal, nonregistered entry point
  1072.             of a function to any indirect function pointers whether they are
  1073.             fully prototyped or not (e.g.  void (*func)() or void (*func)(int)
  1074.             )
  1075.  
  1076.             -mRR assigns either the registered or normal entry point to
  1077.             function pointers depending on whether they are prototyped or not
  1078.             (and any calls made through these function pointers will use the
  1079.             registered args method).
  1080.  
  1081.             || WARNING: -mR cannot be used if you make c.lib calls that take
  1082.             || call-back functions as arguments.
  1083.  
  1084.             -mr and -mRR CAN be used, however with -mRR you must be careful to
  1085.             supply the registered entry point.
  1086.  
  1087.             || WARNING: AMIGA.LIB routines that take call-back functions as
  1088.             || arguments must be given non-registered entry points.
  1089.  
  1090.             Thus if you use -mRR you MUST qualify the procedure or function
  1091.             pointer type specification with __stkargs to entire it has a
  1092.             normal entry point.
  1093.  
  1094.   -mw addr  Used for making romable executables, Do not use to create AMIGA
  1095.             executables
  1096.  
  1097.             «» Beginner's Note: Do not use this option
  1098.  
  1099.             This option is another data model, called the ABSOLUTE-WORD data
  1100.             model.  Source files compiled with this option generate
  1101.             absolute-word data references to access data objects instead of
  1102.             A4-relative or absolute-long.  The base of the data segment must
  1103.             be specified as decimal, 0octal, or 0xHEX.
  1104.  
  1105.             Since absolute-word is used exclusive of A4-relative, the compiler
  1106.             will now use A4 for register variables.  You may NOT mix -mw
  1107.             modules with small-data models.
  1108.  
  1109.             The ROMABLE program is usually run on the executable generated by
  1110.             DLink to generate a ROM.
  1111.  
  1112.   -ma addr  Used for making romable executables, do not use to create Amiga
  1113.             executables
  1114.  
  1115.             «» Beginner's Note: Do not use this option
  1116.  
  1117.             This option specifies to the compiler and linker that the
  1118.             resulting code is intended to be relocated to a permanent data
  1119.             address, that specified by addr in decimal, 0octal, of 0xHEX.
  1120.  
  1121.             Unlike -mw, -ma assumes that the data segment can be placed
  1122.             anywhere.  The ROMABLE program is usually run on the executable
  1123.             generated by DLink to generate a ROM.
  1124.  
  1125.             You may still specify a data model, -md or -mD, to Be with this
  1126.             option.  Unlike -mw, -ma does NOT touch the A4 register and thus
  1127.             may be mixed with the small-data model.  See the section on
  1128.             generating Romable code.
  1129.  
  1130.       -rom  Set up options for generating romable code
  1131.  
  1132.             «» Beginner's Note: Do not use this option
  1133.  
  1134.             Like -l0, -rom disables automatic inclusion of a startup file (you
  1135.             must specify your own) and libraries.  However, x.o is still
  1136.             included to sink any autoinit code.  Your startup code must handle
  1137.             the appropriate model and call autoinit code before calling your
  1138.             program main
  1139.  
  1140.             This option is used to support ROMed firmware, i.e.  non-Amiga
  1141.             executables.  You should never link with c.lib.  Instead, a new
  1142.             library, rom.lib, is available.
  1143.  
  1144.             rom.lib contains no static or global references and thus works
  1145.             with any data model, and only completely self-contained routines
  1146.             are included.  The only data rom.lib uses is stack-based.  All
  1147.             rom.lib routines are completely reentrant, including [v]sprintf()
  1148.             !
  1149.  
  1150.     -proto  Prototype checking and optimizations
  1151.  
  1152.             When this option is used, an ERROR message will be generated for
  1153.             any call that is not prototyped.  This option is useful to ensure
  1154.             that you have properly prototyped routines (when you use
  1155.             prototypes), especially when floats and doubles are passed and
  1156.             indirect function pointers are used (they must be prototyped as
  1157.             well!).
  1158.  
  1159.             In the future this will enable stack-argument optimization. 
  1160.             Currently, chars and shorts are extended to long's when pushed
  1161.             onto the stack for a subroutine call.  In the future if the -proto
  1162.             option is used these objects will be pushed as shorts and not
  1163.             extended.
  1164.  
  1165.      -prof  enable profiling for source modules
  1166.  
  1167.     -prof1  same as -prof
  1168.  
  1169.     -prof2  enable profiling for source modules and c*p.lib
  1170.  
  1171.     -prof3  enable profiling for source mods, c*p.lib, and amiga*p.lib
  1172.  
  1173.             Enable profiling.  You may compile some or all your source modules
  1174.             with profiling enabled.  Any -prof* option will enable profiling
  1175.             for compiled source modules.  -prof2 will cause DCC to link with a
  1176.             profiled c*p.lib while -prof3 will cause DCC to link with a
  1177.             profiled c*p.lib and amiga*p.lib (the ultimate).
  1178.  
  1179.             To profile c*.lib and/or amiga*.lib functions the equivalent
  1180.             c*p.lib and amiga*p.lib must exist.  These libraries are most
  1181.             likely lharc'd in DCC2:dlib/ or DCC3:dlib/ but if not, registered
  1182.             users may create any link library from the library source.
  1183.  
  1184.         -r  Make executable residentable with separate CODE & DATA hunks 
  1185.  
  1186.        -pr  Make executable residentable w/ no relocation hunks
  1187.  
  1188.        -pi  Make executable NON-residentable w/ no relocation hunks
  1189.  
  1190.             «» Beginner's Note: Just use -r to get residentable executables
  1191.             «» and do not worry about these other options.
  1192.  
  1193.             -pr/-pi generate 'position independant' code also useful for ROMed
  1194.             applications.  NOTE that -pi and -pr force const items to be
  1195.             referenced pc-relative as well, causing -ms and -mS to do the same
  1196.             thing (when combined with -pr/-pi)
  1197.  
  1198.             Code size is limited to 32k bytes when you use -pr or -pi
  1199.  
  1200.             Refer to the RESIDENTABILITY section in Chapter 5 for a discussion
  1201.             of these options
  1202.  
  1203.             :: NOTE: You may not make data references within const declared
  1204.             :: objects when using the -r/-pr options.
  1205.  
  1206.             This is because the CODE hunk is shared between running instances
  1207.             of the program and these address references would be different
  1208.             between the instances.
  1209.  
  1210.             However, if you are using the -ms option, string constants will be
  1211.             in the code section and thus no problem.
  1212.  
  1213.  -O outdir  Specify directory that is to contain output executable, object, or
  1214.             assembly files (used when specifying multiple source files)
  1215.  
  1216.             -O is useful to tell the compiler where to put the objects when
  1217.             you use dcc to compile and link a whole bunch of files at once. 
  1218.             In this case, the -o option can still be used to specify where to
  1219.             put the final executable.
  1220.  
  1221.             :: NOTE: The -O name is used as a prefix so if you are specifying
  1222.             :: a directory be sure it has a ':' or '/' on the end.
  1223.  
  1224.  -T tmpdir  Specify the temporary directory used to hold preprocessed source
  1225.             files and temporary assembly files...  files that will be deleted
  1226.             after use.
  1227.  
  1228.             :: NOTE: The -T name is used as a prefix so if you are specifying
  1229.             :: a directory be sure it has a ':' or '/' on the end.
  1230.  
  1231.             The default is T:.  This option is useful in low-memory situations
  1232.             where you may decide to put intermediate files elsewhere.  Putting
  1233.             intermediate files on your HD or floppy slows down compilation by
  1234.             an order of magnitude, but if you are running on a system with
  1235.             little memory you may not have a choice.
  1236.  
  1237.         -s  Include symbolic debugging information in the executable. (dlink
  1238.             opion)
  1239.  
  1240.             This option includes the symbol table in the resulting executable
  1241.             and is passed to dlink.  When using DOBJ to disassemble an
  1242.             executable, DOBJ will use the symbol table to generate a more
  1243.             symbolic dump.
  1244.  
  1245.         -S  Alternate section naming op for libraries
  1246.  
  1247.             When making libraries: uses alternate section naming conventions
  1248.             so that all initialized data in the module will be placed before
  1249.             any initialized data in non -S modules (i.e.  normal linked object
  1250.             files).  Any library BSS will be placed before non-library BSS. 
  1251.             Thus, the final ordering in the final executable will be:
  1252.  
  1253.             LIBDATA
  1254.             PROGRAMDATA
  1255.             LIBBSS
  1256.             PROGRAMBSS
  1257.  
  1258.             Thus, if your program contains >64K Bytes of BSS you can still
  1259.             link with a library that tries to reference its own BSS using the
  1260.             small-data model.  If your library declares only initialized data
  1261.             (i.e.  int x = 0; ), then you can link with the library even if
  1262.             your program declares >64KBytes of *initialized* data !
  1263.  
  1264.         -v  Display commands as DCC executes them.
  1265.  
  1266.             -new Checks timestamps for source/destination and only
  1267.             compiles/assembles if object is outdated or does not exist.  Used
  1268.             to make DCC a standalone make.
  1269.  
  1270.         -f  Fast / ^c handling for 1.3
  1271.  
  1272.             This option is used for 1.3 only.  You MUST be using the Commodore
  1273.             shell (NewShell) and if you make programs resident you MUST use
  1274.             the commodore C:Resident command.
  1275.  
  1276.             This option will probably not work if you use WShell or ARPShell
  1277.             under 1.3.  This option allows DICE to take short cuts to run
  1278.             sub-programs and allows ^C to be propogated to said programs. 
  1279.             This option is useful to set permanently in your DCCOPTS ENV:
  1280.             variable if you run under 1.3
  1281.  
  1282.             DICE under 2.0 has no such problems and will run sub programs
  1283.             optimally, including propogation of ^C.
  1284.  
  1285.      -frag  FRAGment (linker option).
  1286.  
  1287.             Tell linker not to combine all code hunks together or combine all
  1288.             data hunks together.  Cannot be used if the -r or -mw options are
  1289.             used. Generally only useful if the large-data model is used.  Not
  1290.             entirely supported yet.
  1291.  
  1292.       -ffp  Set fp library for floats
  1293.  
  1294.             «» Beginner'S Note: When using single precision floating point
  1295.             «» this option, use of the original ffp libraries, will make the
  1296.             «» program portable across all Amigas.
  1297.  
  1298.             Otherwise only amigas that have the Commodore
  1299.             MathIeeeSing*.library libraries will be able to run the program.
  1300.  
  1301.             If not specified, mathieeesingtrans.library and
  1302.             mathieeesingbas.library are used.  These are new 2.0 libraries
  1303.             that may not exist on all machines yet.
  1304.  
  1305.             If specified, mathtrans.library is used ..  Motorola's FFP float
  1306.             library.
  1307.  
  1308.             :: NOTE: IF -ffp is used, be warned that conversion from floats to
  1309.             :: doubles and back again is not entirely reliable.
  1310.  
  1311.        -d#  Set debugging level (# = a number), used for compiler diagnostics
  1312.             only.
  1313.  
  1314.    -d opts  Specify any combination of debugging options.  These options may
  1315.             be combined in one -d option.
  1316.  
  1317.             Currently no options are defined.
  1318.  
  1319.        -gs  Generate Dynamic Stack Code.  This generates code on every
  1320.             subroutine call to check available stack.  If available stack
  1321.             falls below 2K a new stack frame is allocated which will be
  1322.             deallocated when the subroutine returns.
  1323.  
  1324.             If the allocation fails, stack_abort() is called.  If this routine
  1325.             is not defined by you, the library stack_abort() will call
  1326.             abort().
  1327.  
  1328.             This option is extremely useful when compiling UNIX code that
  1329.             expects infinite stack.
  1330.  
  1331.      -chip  CHIP force (linker option).
  1332.  
  1333.             Tell linker to force all hunks into CHIP memory.  You should
  1334.             generally not use this option.  Instead, use the __chip keyword
  1335.             for those specific data items that need to be in CHIP memory.
  1336.  
  1337.             :: NOTE: CHIP data items are accessed using the large-data model,
  1338.             :: thus you cannot create residentable executables that contain
  1339.             :: __chip declarations Unless they are also const objects --
  1340.             :: read-only.
  1341.  
  1342.      -unix  Causes DICE to use DLIB:uc*.lib instead of DLIB:c*.lib ...  the
  1343.             uc*.lib is exactly the same as the normal c*.lib except that all
  1344.             filenames are assumed to be UNIX names ..  that is, a beginning
  1345.             slash is converted to ':' (root of the current volume), "./" is
  1346.             ignored, and "../" is converted to "/" for all file accesses.
  1347.  
  1348.             This makes porting and usage of UNIX programs easier.
  1349.  
  1350.     -aztec  The front end attempts to run Aztec executables
  1351.  
  1352.   -lattice  The front end attempts to run Lattice executables
  1353.  
  1354.       -sas  same as -lattice
  1355.  
  1356.             These options allow one to write a single DMakefile able to handle
  1357.             compilation under any compiler, assuming the source is compilable
  1358.             under any compiler.
  1359.  
  1360.             These are very limited options and may not work across new
  1361.             versions of Aztec or Sas/C
  1362.  
  1363.        -//  This option enables C++ style // comments.  This form of
  1364.             commenting begins with a // causing it and the remainder of the
  1365.             line to be considered a comment.
  1366.  
  1367.    -no-env  This option disables DCCOPTS.  DCC will not process options in the
  1368.             DCCOPTS enviroment variable.
  1369.  
  1370.             The ENV:DCCOPTS enviroment variable may contain additional
  1371.             options.
  1372.  
  1373.             ENV: must exist for DCC to run, even if you do not have a DCCOPTS
  1374.             enviroment variable.  If you do not use ENV: then assign it to
  1375.             RAM:
  1376.  
  1377.             1> assign env: ram:
  1378.  
  1379.     EXAMPLES:
  1380.         Example #1.  Compile hello.c to executable.  The objects will be left
  1381.         in T:
  1382.  
  1383.         1> dcc hello.c -o ram:hello 1> ram:hello
  1384.  
  1385.         Example #2.  Compile hello.c to executable and put the object file in
  1386.         X:
  1387.  
  1388.         1> dcc hello.c -o ram:hello -TX:
  1389.  
  1390.         Example #3.  Compile hello.c into object into RAM: then link with
  1391.         symbols
  1392.  
  1393.         1> dcc -c hello.c -o ram:hello.o
  1394.         1> dcc ram:hello.o -o ram:hello -s
  1395.  
  1396.         Example #4.  Compile foo.c and link with an already compiled object
  1397.         file gar.o to produce an executable.  foo.o is placed in T:
  1398.  
  1399.         1> dcc foo.c gar.o -o ram:foogar
  1400.  
  1401.     PREPROCESSOR
  1402.         Predefined Symbols:
  1403.  
  1404.         Symbol, Type, Usage
  1405.  
  1406.         __LINE__,  integer constant, current line number
  1407.  
  1408.         __DATE__ ,  string, current date
  1409.  
  1410.         __TIME__,  string, current time
  1411.  
  1412.         __FILE__,  string, current file
  1413.  
  1414.         __BASE_FILE__,  string, base source file
  1415.  
  1416.         __STDC__, boolean,
  1417.  
  1418.         mc68000, integer constant,
  1419.  
  1420.         _DCC, integer constant,
  1421.  
  1422.         AMIGA, integer constant,
  1423.  
  1424.         _FFP_FLOAT, boolean, set if single precision floats are in FFP format
  1425.  
  1426.         _SP_FLOAT, boolean, set if single prec.  floats are in IEEE-SING
  1427.         format (default)
  1428.  
  1429.         __BASE_FILE__ allows specification of the actual name of the source
  1430.         file from within an include file.
  1431.  
  1432.         :: NOTE: There are no limits to symbol and macro lengths.
  1433.  
  1434.     SEE ALSO
  1435.         das, dc1, dcpp, dlink
  1436.  
  1437.  
  1438. dice/dcpp                                                          dice/dcpp
  1439.  
  1440.     NAME
  1441.         DICE Preprocessor
  1442.  
  1443.     SYNOPSIS
  1444.         dcpp sourcefile [-o outfile] [-I includedir ...] options
  1445.  
  1446.     DESCRIPTION
  1447.         DCPP automatically scans DINCLUDE:, DINCLUDE:PD/, and DINCLUDE:AMIGA/
  1448.         .  Any -I option directories are searched in sequence BEFORE DCPP's
  1449.         default search path.  The last default directory, DINCLUDE:AMIGA/, may
  1450.         be modified with the -1.x and -2.x options, see below.
  1451.  
  1452.         Note that DINCLUDE:PD/  is meant to be a place to put public domain
  1453.         header files so as not to clutter the top level DINCLUDE: directory.
  1454.  
  1455.         As with all DCC commands, the space between the option and an
  1456.         associated file/dir argument is optional.
  1457.  
  1458.         DCC normally runs DCPP before DC1
  1459.  
  1460.         The following symbols are defined by default
  1461.  
  1462.         Symbol, Category, Meaning
  1463.  
  1464.         mc68000, Processor, running on a 68000
  1465.  
  1466.         _DCC, Compiler, 'DCC' compiler
  1467.  
  1468.         __STDC__, Language, ANSI __STDC__
  1469.  
  1470.         AMIGA, Platform, AMIGA computer
  1471.  
  1472.          -1.N  Selects 1.x compatibility for the Preprocessor.  If specified, all
  1473.             system include files are pull from
  1474.  
  1475.       -2.N  This option selects the OS.  If not specified, DCPP searches
  1476.             dinclude:amiga for amiga includes.  If specified, DCPP searches
  1477.             dinclude:amiga1N or dinclude:amiga2N for Amiga includes instead.
  1478.  
  1479.             DCC supports this option and passes it along to dcpp.  This allows
  1480.             developers to compile under either 1.3 or 2.0 (or whatever) with
  1481.             the flick of an option.  DCC also uses a different amiga.lib.
  1482.  
  1483.      -d[#]  This option turns on DCPP debugging
  1484.  
  1485.     -ofile  This option sets the output file, otherwise stdout is used.
  1486.  
  1487.       -ffp  Passed from DCC, tells preprocessor to define _FFP_FLOAT.  If not
  1488.             specified, preprocessor defines _SP_FLOAT.  This exists to better
  1489.             support alternate floating point models in header files.
  1490.  
  1491.  -Dvar[=val]
  1492.             This option predefines a symbol or macro.
  1493.  
  1494.    -E file  specify stderr file, any errors are appended to file instead of to
  1495.             stdout.  Useful for batch compiles
  1496.  
  1497.         -U  This option undefines the following symbols:
  1498.  
  1499.             __STDC__ mc68000 _DCC AMIGA
  1500.  
  1501.  -Hprecomp=header
  1502.             Enable use/creation of precompiled header files.  Example:
  1503.  
  1504.             -Ht:defs.m=defs.h
  1505.  
  1506.             see chapter 5 for more information.
  1507.  
  1508.        -I0  This option causes DCPP to *NOT* include any default directories
  1509.             in the include search list.
  1510.  
  1511.     -I dir  This option adds the specified directory to the include search
  1512.             list.  A hanging slash on the end of the path is not required. 
  1513.             The space is optional.
  1514.  
  1515.        -//  Enable C++ style // comments.  The remainder of the line after //
  1516.             is encountered is interpreted as a comment.  This differs from /*
  1517.             style commenting in that no explicit comment-terminator is
  1518.             required.
  1519.  
  1520.     -notri  Disable tri-graph scan pass.  Note that the tri-graph pass is
  1521.             implemented in assembly and does not slow down preprocessing in
  1522.             any noticable fashion, you should not disable tri-graphs unless
  1523.             you need to.
  1524.  
  1525.     SEE ALSO
  1526.         dcc, dc1
  1527.  
  1528.  
  1529. dice/diff                                                          dice/diff
  1530.  
  1531.     NAME
  1532.         File Compare Utility
  1533.  
  1534.   SYNOPSIS  diff options oldfile newfile
  1535.  
  1536.     DESCRIPTION
  1537.         diff is used to compare the contents of two text files.
  1538.  
  1539. dice/dlink                                                        dice/dlink
  1540.  
  1541.     NAME
  1542.         DICE Linker
  1543.  
  1544.     SYNOPSIS
  1545.         dlink options files libraries
  1546.  
  1547.     DESCRIPTION
  1548.         Options may occur anywhere on the command lines.  Any file ending in
  1549.         .o or .obj is assumed to be an object file.  Any file ending in .l or
  1550.         .lib is assumed to be a library.  Any file name beginning with @
  1551.         specifies a text file containing a further list of files.
  1552.  
  1553.         File ordering is maintained.  Section ordering is maintained.  All
  1554.         sections of the same name are coagulated together with ordering
  1555.         maintained.
  1556.  
  1557.         :: NOTE: Inter-section ordering is not maintained within a library
  1558.         :: since library modules are random included.  However, ordering is
  1559.         :: maintained *between* libraries.
  1560.  
  1561.         All object files specified are included in the final executable.  All
  1562.         libraries specified are searched at the point they are specified (that
  1563.         is, specifying an object file that references a symbol defined in a
  1564.         library specified BEFORE the object file will cause an undefined
  1565.         symbol error).  Normally an object file is specified after a library
  1566.         to terminate an autoinit or autoexit section.
  1567.  
  1568.         You do not have to order object files within a library, DLink will
  1569.         automatically make as many passes as required to handle all internal
  1570.         library references.  However, ordering object files will make DLink go
  1571.         faster.
  1572.  
  1573.         Symbols defined in object files overide symbols defined in libraries.
  1574.         Symbols defined in libraries specified before later libraries overide
  1575.         symbols defined in later libraries.  Symbols defined in a library and
  1576.         also defined in a later specified object module causes an error. -o
  1577.         execname name of executable
  1578.  
  1579.         -s  Include symbolic information.
  1580.  
  1581.             :: NOTE: if -r is used symbolic info for the data sections will
  1582.             :: point to the statically init'd stuff, NOT The actual data space
  1583.             :: (in BSS) referenced by the code.  This is a bug.
  1584.  
  1585.      -frag  Fragment output file (default is to coagulate all hunks of the
  1586.             same type regardless of name).  If frag is specified then only
  1587.             hunks of the same type AND name are coagulated.
  1588.  
  1589.             see fragmentation note at bottom
  1590.  
  1591.     -r[es]  Resident link.
  1592.  
  1593.        -pi  Position independant non-residentable (i.e.  only one copy of the
  1594.             data but also no relocation hunks)
  1595.  
  1596.             -pr residentable position independant
  1597.  
  1598.  -Ppostfix  specify library name postfix.  If DLink cannot find the library as
  1599.             specified it will append the postfix and try again.  Used by DCC
  1600.             to specify the memory model.
  1601.  
  1602.   -mw addr  specify absolute data base
  1603.  
  1604.   -ma addr  specify absolute data base
  1605.  
  1606.             Both options do exactly the same thing and are in duplicate to
  1607.             conform to DCC's options.
  1608.  
  1609.             DLink will resolve all Absolute-Word addresses but not all
  1610.             Absolute-Long addresses.  This is left up to the ROMABLE program
  1611.             which generates a raw binary image of the program that can then be
  1612.             transfered to an EPROM.
  1613.  
  1614.             :: NOTE: Do not use this option when generating Amiga executables.
  1615.  
  1616.      -d[#]  debug mode (spews lots of debugging junk out)
  1617.  
  1618.    -E file  specify stderr file, any errors are appended to the file instead
  1619.             of to stdout.  Useful for batch compiles
  1620.  
  1621.      -chip  chip-only - forces all hunks into CHIP memory
  1622.  
  1623.        -L0  remove default library search path, including all explicitly
  1624.             specified (-L dir) directories up to this point.
  1625.  
  1626.     -L dir  add the specified directory to the library search path.  If the
  1627.             object module or library can not be found in the current
  1628.             directory, directories specified with -L are searched.  -L
  1629.             directories are searched before the default library directory
  1630.             (DLIB:), assuming it was not removed with -L0 .
  1631.  
  1632.             Note that the directory path specified by -L is used to search for
  1633.             libraries AND object modules.
  1634.  
  1635.             A trailing '/' is optional
  1636.  
  1637.  -Ppostfix  This allows you to specify -lc -Ps and DLink will automatically
  1638.             look for cs.lib ...  you can specify a postfix that occurs before
  1639.             the .lib in the library name here.  If DLink cannot find the
  1640.             library as it is named by default it will try it with the postfix.
  1641.  
  1642.             DCC uses this to supply the memory model to DLINK also allowing
  1643.             the user to say -lm in DCC and have it find MS.LIB if you are
  1644.             using the small-data model.
  1645.  
  1646.     CREATING A
  1647.     LIBRARY
  1648.         DLink libraries are standard Amiga libraries...  simply join one or
  1649.         more object modules together and rename the result with a .lib
  1650.         extension.
  1651.  
  1652.     LINKER
  1653.     SYMBOLS
  1654.         DLink generates the following special symbols to aid in program
  1655.         startup:
  1656.  
  1657.         Symbol, Meaning
  1658.  
  1659.         __ABSOLUTE_BAS, Base of data in volatile space.  This symbol is NOT
  1660.         defined for normal residentable programs since the base address is not
  1661.         known (must be allocated run-time)
  1662.  
  1663.         __DATA_BAS, Base of data in non-volatile space.  This symbol points to
  1664.         a read-only copy of the initialized data for a program.  For
  1665.          Non-residentable programs this is the same as __ABSOLUTE_BAS.
  1666.         For residentable programs this points to a read-only copy of the
  1667.          initialized data that the program can duplicate on startup.
  1668.         For programs linked with an absolute base address for data this points
  1669.         to the end of the CODE section.  The ROMABLE program always generates
  1670.         a ROM copy of the initialized data just after the CODE section (which
  1671.         startup code must copy into RAM)
  1672.  
  1673.         __DATA_LEN, Length of data space is longwords.  i.e.  __DATA_LEN*4
  1674.         yields the number of bytes of initialized data.  This is used by
  1675.         startup code to copy read-only initialized data to volatile space
  1676.         (residentable and data-absolute programs)
  1677.  
  1678.         __BSS_LEN, Length of bss space in longwords.  i.e.  __BSS_LEN*4 yields
  1679.         the number of bytes of uninitialized (BSS) data.  This is used in
  1680.         combination with __DATA_LEN to allocate the DATA+BSS space for
  1681.         residentable programs,, and clear the BSS space for non-residentable
  1682.          and absolute-data-base programs.
  1683.         
  1684.         The BSS space occurs after the DATA space unless the -frag option is
  1685.         used.
  1686.  
  1687.         __RESIDENT5D, This symbol is set to 0 if the -r option was used and 1
  1688.         if the -r option was not used.  If set to 1 (-r option)
  1689.  
  1690.         Programs linked with the -mw or -ma options obviously do not
  1691.         'allocate' their data space since it is predefined.  Most Amiga
  1692.         programmers will never use the -mw or -ma options, by the way.
  1693.  
  1694.     SMALL DATA MODEL
  1695.         The small data model uses A4 relative addressing.  The linker sets up
  1696.         all relative offsets such that A4 must be initialized by startup code
  1697.         the BaseOfInitializedData + 32766 for A4-relative references to access
  1698.         the appropriate address.
  1699.  
  1700.     RESIDENT
  1701.         If the -r options is given then NO BSS SPACE is allocated after the
  1702.         data space...  the startup code MUST allocate a data+bss space as
  1703.         shown above.  DLink will give error messages for any absolute data
  1704.         references that occur (except the __DATA_BAS symbol which must be used
  1705.         to copy the static data to the newly allocated data+bss memory on
  1706.         program startup).
  1707.  
  1708.         DLink will give an error message if any data-data reloco32s exist when
  1709.         you specify the -r option as such relocations would be incorrect when
  1710.         copied to the newly allocated data+bss space.  DC1 understands this
  1711.         and will produce autoinit code to handle any such static data
  1712.         relocations that occur in your C code when the -r option is given to
  1713.         compile a C program.
  1714.  
  1715.         However, DLink does allow data-data relocations to occur if an
  1716.         absolute data base is specified along with the -r option.  This is
  1717.         used only when making ROMABLE code.
  1718.  
  1719.     PC-RELATIVE
  1720.         Because the linker will insert a jump table for PC-RELATIVE references
  1721.         to different hunks (after coagulation) or where the range is larger
  1722.         than +/-32K, data should not be placed into a code segment and be
  1723.         referenced via an external label(pc) unless you are positive the
  1724.         reference is within +/-32K.  This can only happen when referencing
  1725.         between like-named code hunks.  NOTE that the jump table is tagged
  1726.         onto the end of the section the jump(s) occur in and thus you do not
  1727.         want to have any autoinit/autoexit code that might possibly generate a
  1728.         jump table (since the whole idea with autoinit is that the code falls
  1729.         through to other autoinit code until the terminating section in x.o's
  1730.         RTS).
  1731.  
  1732.         Currently dlink cannot handle inter-module PC-RELATIVE references
  1733.         beyond +/-32K (i.e.  when one object file has more than 32K of code).
  1734.         An error will occur.
  1735.  
  1736.         Note that if -frag is used you cannot make PC-RELATIVE calls between
  1737.         sections of differing names ever, or make a program resident.  The
  1738.         -frag option is almost never used on untested.
  1739.  
  1740.     OVERLAYS
  1741. (NOT SUPPORTED)
  1742.         Overlays are not supported as yet.
  1743.  
  1744.         :: NOTE: When -frag is specified, the linker will not create a special
  1745.         :: combined data+bss hunk (so data and bss can both be referenced with
  1746.         :: one base variable).
  1747.  
  1748.         However, when -frag is NOT specified, the linker will stil not
  1749.         necessarily combine ALL data hunks into one big hunk and ALL bss hunks
  1750.         into one big hunk.  Any data or bss hunk with special upper bits set
  1751.         (e.g. to force it into chip) is not combined into these special hunks,
  1752.         and any data or bss hunk whos NAME begins with 'far' (upper or lower
  1753.         case) will also not be considered.
  1754.  
  1755.     EXAMPLE
  1756.         This is what DCC gives the linker to link the program foo.c:
  1757.  
  1758.         dlink dlib:c.o @tmp dlib:x.o -o ram:foo
  1759.  
  1760.         Where tmp contains:
  1761.  
  1762.         foo.o
  1763.         dlib:c.lib
  1764.         dlib:amiga.lib
  1765.         dlib:auto.lib
  1766.  
  1767.         Basically it tells dlink to link the startup code, c.o, then the
  1768.         program object module(s) (foo.o), then c.lib, amiga.lib, and auto.lib,
  1769.         then finally x.o.
  1770.  
  1771.         DCC handles all this for you
  1772.  
  1773.         auto.lib contains autoinit code for certain selected libraries,
  1774.         including the dos.library.  Autoinit code is brought in whenever a
  1775.         given library base symbol has been referenced BUT NOT DEFINED. 
  1776.         auto.lib defines the symbol and generates autoinit code to open the
  1777.         library and autoexit code to close the library.  To maintain
  1778.         portability you probably do not want to use this automatic
  1779.         library-openning feature yourself, it is really meant to support
  1780.         certain actions of the DICE library (such as floating point support).
  1781.  
  1782.         x.o terminates the autoinit and autoexit sections with an RTS
  1783.         instruction.  The autoinit and autoexit sections are called from the
  1784.         startup code c.o.
  1785.  
  1786.  
  1787. dice/dmake                                                        dice/dmake
  1788.  
  1789.     NAME
  1790.         Make Utility
  1791.  
  1792.     SYNOPSIS
  1793.         dmake [file]
  1794.  
  1795.     DESCRIPTION
  1796.         The idea with DMake is to provide a powerful make utility through
  1797.         general features rather than specialized hacks.  DMake is governed by
  1798.         a few simple rules that can be combined into incredibly powerful
  1799.         operations.
  1800.  
  1801.         Generally you simply run DMake and have a list of dependancies in your
  1802.         DMakefile which DMake then executes.  The DMakefile may contain three
  1803.         different kinds of lines:
  1804.  
  1805.         10) COMMENTS -- Any line beginning with a '#' is a comment and ignored
  1806.  
  1807.         # This DMakefile generates an executable for fubar
  1808.         # The compiler options are as follows ...
  1809.  
  1810.         11) ASSIGNMENTS -- Any line of the form SYMBOL = ...  is considered an
  1811.         11) assignment.  Any variable references from within the assignment
  1812.         11) will be resolved immediately.
  1813.  
  1814.         CFLAGS= -r SRCS= x.c y.c z.c
  1815.  
  1816.         12) DEPENDANCIES: -- A line containing a list of symbols, a colon, and
  1817.         12) more symbols is assumed to be a dependancy.  Note that you cannot
  1818.         12) have a raw filename with a colon in it as that confuses DMake. 
  1819.         12) Instead, use an ASSIGNMENT variable.
  1820.  
  1821.         Following the dependancy line is zero or more command lines --
  1822.         commands to run to resolve the dependancy, terminated with a blank
  1823.         line.
  1824.  
  1825.         :: NOTE: Not only is a zero-command dependancy allowed, it is
  1826.         :: sometimes necessary.
  1827.  
  1828.         A particular destination may have only ONE command list so if you have
  1829.         something like
  1830.  
  1831.         a.o : a.c
  1832.  
  1833.         with a command list to compile the source into an object you can also
  1834.         have another dependancy such as 'a.o : defs.h' which would NOT have
  1835.         any associated command list.
  1836.  
  1837.         dst1 ...  dstN : src1 ...  srcN command1 command2 ...
  1838.         dst1 ...  dstN : src1 ...  srcN command1 command2 ...
  1839.  
  1840.         Finally, note that a dst* or src* symbol does not need to be a
  1841.         filename.  It is perfectly valid to make up dummy names which are then
  1842.         used as the lhs of a dependancy that collects other dependancies
  1843.         together.
  1844.  
  1845.     DEPENDANCIES
  1846.         When declaring dependancies you may use four different forms.  The
  1847.         first form is to have a single destination and several sources.  This
  1848.         is intreted to mean that ALL the sources must be resolved before the
  1849.         single destination can be resolved via the command list for the
  1850.         dependancy.  The special variable, %(left), is set to the dst symbol
  1851.         and the special variable %(right) is set to ALL of the src symbols
  1852.  
  1853.         For example, this form would be used to indicate that an executable
  1854.         depends on all the objects being resolved before you can run the link.
  1855.  
  1856.         dst : src1 src2 src3 ...  srcN
  1857.  
  1858.         The second form is the most useful in that it allows you to specify
  1859.         multiple 1 : 1 dependancies.  Thus, you can specify, for example, that
  1860.         each object file depends on its source file counterpart for ALL the
  1861.         files in your project on a single line and have a single command list
  1862.         representing what to do (to compile a source file into an object,
  1863.         say).
  1864.  
  1865.         In this case %(left) and %(right) are set to each dst* : src* pair
  1866.         individually and the command list is run for any individual pair that
  1867.         is out of date.
  1868.  
  1869.         dst1 dst2 dst3 ...  dstN : src1 src2 src3 ...  srcN
  1870.  
  1871.         The next form may be used to specify that many files depend on one
  1872.         file being resolved.  An example of usage would be to make all the
  1873.         object files depend on one header file.  The command list, if any, is
  1874.         run for each dst* : src pair with %(left) set to the current dst* and
  1875.         %(right) set to the single source.
  1876.  
  1877.             dst1 dst2 dst3 ...  dstN : src
  1878.  
  1879.         The last form is esoteric but sometimes useful.  EACH dst* on the left
  1880.         hand side depends on the entire right hand side.  You can have an
  1881.         arbitrary number of symbols on either side.  %(left) will be set to a
  1882.         particular DST while %(right) will be set to all of the SRCs.
  1883.  
  1884.         for example, you could specify $(OBJS) :: $(HDRS) -- make all objects
  1885.         depend on all headers causing a recompile to occur if any header is
  1886.         modified.
  1887.  
  1888.         dst1 dst2 dst3 ...  dstN :: src1 src2 ...  srcI
  1889.  
  1890.     WILDCARDS
  1891.         DMake's most powerful feature is an easy to use file list replacement
  1892.         through options in a variable specification.  You may insert the
  1893.         contents of any variable using the form:
  1894.  
  1895.         $(SYMBOL)
  1896.  
  1897.         Furthermore, you can make modifications to the contents of the
  1898.         variable on the fly using:
  1899.  
  1900.         $(SYMBOL:wildcard)
  1901.  
  1902.         only those files which match wildcard
  1903.  
  1904.         $(SYMBOL:wildcard:wildcard)
  1905.  
  1906.         matching files and also do a conversion
  1907.  
  1908.         Simple */? wildcarding is used.  A wildcard may contain a colon or
  1909.         other punctuation but if it does you MUST surround it with quotes. 
  1910.         Here is a quick example:
  1911.  
  1912.         SRCS= a.c b.c c.c d.c xx.a
  1913.         OBJS= $(SRCS:*.c:"dtmp:%1.o")
  1914.         
  1915.         all: echo $(OBJS)
  1916.  
  1917.         Will Produce
  1918.  
  1919.         dtmp:a.o dtmp:b.o dtmp:c.o dtmp:d.o
  1920.  
  1921.         The first wildcard specification restricts which files from the list
  1922.         are to be taken -- 'xx.a' was ignored, as you can see.  Each '*' or
  1923.         '?' in the first wildcard specification corresponds to %N
  1924.         specifications in the second wildcard specification.  You can prepend,
  1925.         insert, or append text and freely mix or ignore items matched to
  1926.         create your destination file list.
  1927.  
  1928.         This capability allows you to specify your source files EXACTLY ONCE
  1929.         in the DMakefile and then use the file munging capability to convert
  1930.         them to the object file list, etc...
  1931.  
  1932.         You can embed variables within variables as with the following example
  1933.         (note that this time xx.a is included):
  1934.  
  1935.         OD= dtmp:fubar/
  1936.         SRCS= a.c b.c c.c d.c xx.a
  1937.         OBJS= $(SRCS:*.?:"$(OD)%1.o")
  1938.         
  1939.         all: echo $(OBJS)
  1940.  
  1941.         Will produce
  1942.  
  1943.         dtmp:fubar/a.o dtmp:fubar/b.o dtmp:fubar/c.o
  1944.         dtmp:fubar/d.o dtmp:fubar/xx.o
  1945.  
  1946.         As a side note, you may also specify '?' and '*' in the destination
  1947.         wildcard.  These are considered dummies and are equivalent to %N where
  1948.         N is incremented from 1..9 for each '?' or '*' encountered.
  1949.  
  1950.         You can use the capability anywhere in the DMakefile.  Another common
  1951.         thing to do is restrict your link line to include only the object
  1952.         files and skip the headers:
  1953.  
  1954.         $(EXE) : $(PROTOS) $(OBJS) $(HDRS)
  1955.         dcc %(right:*.o) -o %(left)
  1956.  
  1957.     ENVIROMENT
  1958.     VARIABLES
  1959.         2.0 local variables and 1.3/2.0 ENV: variables are fully accessible.
  1960.         Under 2.0 you can also modify local variables on the fly. 
  1961.         DMake-specific variables override 2.0 local variables overide ENV:
  1962.         variables.
  1963.  
  1964.         Under 2.0, any command containing '<D', '>', '`', or '|', or is an
  1965.         alias, will be run with System().  Thus, such commands may not be used
  1966.         to modify local variables or the local enviroment.  Also, such
  1967.         commands cannot be ^C'd due to the way AmigaDOS works.
  1968.  
  1969.     LINE CONTINUATION AND ESCAPES
  1970.         Any line may be continued by terminating it with a backslash '\'.  It
  1971.         is possible to escape the special characters '$' and '%' by doubling
  1972.         them though this is only necessary if an open-parenthesis follows the
  1973.         '$' or '%' and you do not want it interpreted as a variable.
  1974.  
  1975.         It is possible to escape ':' and other special characters by assigning
  1976.         them (or a string containing them) to a variable
  1977.  
  1978.     COMMAND
  1979.     SHELL
  1980.         Under 2.0 commands that do not contain any sort of redirection are run
  1981.         with RunCommand().  If a command is an alias or there is some sort of
  1982.         redirection in the arguments it will be run with System().
  1983.  
  1984.         Under 1.3 everything is run with Execute()
  1985.  
  1986.     ADVANCED
  1987.     CAPABILITIES
  1988.         Now, you may have noted earlier that I said you could not have any
  1989.         given left-hand-side with more then one command list.  Take, for
  1990.         example:
  1991.  
  1992.         a.o : a.c dcc %(right) -o %(left)
  1993.         
  1994.         a.o : defs.h <--- illegal to put command list here 
  1995.  
  1996.         Actually, it isn't illegal.  When DMake encounters a dependancy
  1997.         without a command list it will automatically 'force' the next higher
  1998.         level dependancy of the same left-hand-side.  Therefore if you do not
  1999.         have a command list for the lower level left-hand-side things work as
  2000.         you expect.  Note that this requires all such null dependancies to
  2001.         exist AFTER the one that has the command list.
  2002.  
  2003.         If you do have two or more command lists for the same left-hand-side
  2004.         they will run independant of each other according to their individual
  2005.         right hand sides.  If several command lists apply then their order of
  2006.         execution will be bottom-up
  2007.  
  2008.     TEST FOR
  2009.     EXISTANCE
  2010.         Another advanced feature quite useful in fully automating the
  2011.         compilation process is the ability to create a directory tree on the
  2012.         fly.  That is, if you have a projects called 'fubar' and want the
  2013.         objects to go into the directory DTMP:fubar/ you might want to have a
  2014.         dependancy that creates DTMP:fubar if it does not already exist.
  2015.  
  2016.         XX= dtmp:fubar
  2017.         $(XX) : $(XX) makedir %(left)
  2018.  
  2019.  
  2020. dice/dme                                                            dice/dme
  2021.  
  2022.     NAME
  2023.         Editor
  2024.  
  2025.     SYNOPSIS
  2026.         Dme file
  2027.  
  2028.     DESCRIPTION
  2029.         Dme is a full screen programmable editor.
  2030.  
  2031.  
  2032. dice/dobj                                                          dice/dobj
  2033.  
  2034.     NAME
  2035.         Disassemble objects, executables, or Libraries
  2036.  
  2037.     SYNOPSIS
  2038.         DOBJ object_files [-o outfile] [-nd] [-nc] [-d[#]]
  2039.  
  2040.     DESCRIPTION
  2041.         DOBJ disassembles object modules and libraries into assembly.  DOBJ is
  2042.         useful for, say, finding bugs in an assembler.  Most DICE users will
  2043.         use DOBJ to browse through libraries and object modules, and perhaps
  2044.         to check DAS optimizations...  for example, branch optimizations will
  2045.         show up in disassembled object modules that are not otherwise apparent
  2046.         by looking at assembly output (DCC -a).
  2047.  
  2048.         DOBJ generates output to the console unless the -o option is used. 
  2049.         The -d option is for debugging the DOBJ program itself and not
  2050.         normally used.
  2051.  
  2052.  -o filename
  2053.             redirect output
  2054.  
  2055.      -d[#]  Set debug level
  2056.  
  2057.        -nd  Do not show actual data, only display symbol names
  2058.  
  2059.        -nc  Do not disassemble actual code, only display symbol names
  2060.  
  2061.             DOBJ will replace hunk/offset references with symbol names when
  2062.             possible to yield a more readable output, and interprets each hunk
  2063.             according to its type (CODE, DATA, or BSS).
  2064.  
  2065.             There is NO limit to the size of the object file that may be
  2066.             disassembled, but it should be noted that DOBJ can take a while to
  2067.             resolve a large object file's symbols so be patient.  DOBJ does
  2068.             not take up much memory run-time, even when disassembling large
  2069.             object modules.
  2070.  
  2071.             || WARNING: DOBJ does not understand all 68000 instructions.  It
  2072.             || does not understand any 68020/030 instructions yet.
  2073.  
  2074.  
  2075. dice/dprof                                                        dice/dprof
  2076.  
  2077.     NAME
  2078.         Profiler
  2079.  
  2080.     SYNOPSIS
  2081.         DPROF proffile [-call]
  2082.  
  2083.     DESCRIPTION
  2084.         DPROF generates profiling output from the binary data file generated
  2085.         by an executable which was compiled with profiling enabled.
  2086.  
  2087.         In order to use DPROF you must compile your program with the -prof
  2088.         option.  There are three levels of profiling:
  2089.  
  2090.         Dcc Option, Effect
  2091.  
  2092.         -prof1, Profile only your code
  2093.  
  2094.         -prof2, Profile your code and the standard C library
  2095.  
  2096.         -prof3, Profile your code,, the C library,, and the Amiga library tags
  2097.  
  2098.         To use -prof2 you must have installed DLIB:CSP.LIB (small data
  2099.         profiled c.lib) or DLIB:CSRP.LIB (small data profiled c.lib for
  2100.         registered arguments).
  2101.  
  2102.         To use -prof3 you must have installed DLIB:AMIGASP20.LIB (small data
  2103.         profiled amiga.lib) or DLIB:AMIGASRP20.LIB (small data profiled
  2104.         amiga.lib for registerd arguments).
  2105.  
  2106.     USAGE
  2107.  
  2108.         || WARNING: The profiling code is accurate to 20 microseconds under
  2109.         || 2.0, 1/60 second under 1.3.  The profiling code itself will slow
  2110.         || down a program by quite a bit but, in general, the system makes
  2111.         || every attempt to filter out its profiling overhead in the
  2112.         || statistics file (so the grand total time will be less then the
  2113.         || actual amount of time the program took to run).
  2114.  
  2115.         Note, however, that the results will be skewed somewhat anyway, not
  2116.         only due to the overhead of the profiling code, but also due to task
  2117.         switches and other system overhead.  To get accurate results you
  2118.         should only run the executable that is to generate a .dprof file on an
  2119.         unloaded system (i.e.  don't do anything else while the executable is
  2120.         running).  Many calls to very short, quick routines will suffer the
  2121.         most and numbers should be taken more in a qualitative fashion than a
  2122.         quantitative fashion.
  2123.  
  2124.         Keep in mind that it is not necessary to profile everything,
  2125.         particulary for large projects.  You may want most of the system to
  2126.         run at full speed while only profiling a small part of it at a time.
  2127.  
  2128.     EXAMPLE
  2129.         Given a program called example.c:
  2130.  
  2131.         void fubar1(void);
  2132.         void fubar2(void);
  2133.         void loop(long);
  2134.         
  2135.         main(ac, av)
  2136.         char *av[];
  2137.         {
  2138.            short i;
  2139.            for (i = 0; i < 100; ++i)
  2140.            {
  2141.               fubar1();
  2142.               fubar2();
  2143.            }
  2144.            loop(10);
  2145.            fubar1();
  2146.            fubar2();
  2147.         }
  2148.         
  2149.         void fubar1()
  2150.         {
  2151.            short j;
  2152.            for (j = 0; j < 10000; ++j);
  2153.            fubar2();
  2154.         }
  2155.         
  2156.         void fubar2()
  2157.         {
  2158.            short j;
  2159.            for (j = 0; j < 100; ++j);
  2160.         }
  2161.         
  2162.         void loop(n)
  2163.         {
  2164.            if (n)
  2165.               loop(n - 1);
  2166.         }
  2167.  
  2168.         compile and the run the program, then dump the profile.  the DPROF
  2169.         program automatically appends the '.dprof' onto the filename you
  2170.         specify.
  2171.  
  2172.         1> dcc test.c -o test -prof1
  2173.         1> test
  2174.         1> dprof test
  2175.  
  2176.         @($)DPROF V2.06.01  Sep 30 1991         test.dprof
  2177.         
  2178.         GrandTotal:   539.53 mS
  2179.         
  2180.         **** BY ROUTINE ****
  2181.         
  2182.         _main    calls=1      total=  539.53 mS (100.00%) local=   10.37 mS ( 
  2183.          1.92%)
  2184.         _fubar1 calls=101    total=  517.45 mS ( 95.90%) local=  507.75 mS (
  2185.          94.10%)
  2186.         _fubar2 calls=202    total=   20.44 mS (  3.79%) local=   20.44 mS ( 
  2187.          3.79%)
  2188.         _loop    calls=11     total=    0.96 mS (  0.17%) local=    0.96 mS ( 
  2189.         0.17%)
  2190.  
  2191.             \_______/    \_________________________/
  2192.          \__________________________/
  2193.                        total amount of time        amount of time spent in the routine
  2194.         the number of    spent in the routing        not including profiled
  2195.          subroutine
  2196.         calls made to    including all subroutine     calls it may make.
  2197.      
  2198.          the routine      calls.
  2199.                                     The percentage is relative to
  2200.                     Percentage is relative to   the grand total run time
  2201.                     the grand total
  2202.  
  2203.         **** BY PARENT ****
  2204.  
  2205.         total number of calls made to fubar2() and total running time, same as
  2206.         from the first table
  2207.  
  2208.         _fubar2 calls=202    total=   20.44 mS
  2209.         From _fubar1 calls=101    total=    9.69 mS ( 47.43%)     From _main    
  2210.         calls=101    total=   10.75 mS ( 52.56%)
  2211.  
  2212.         number of calls made to fubar2() from fubar1() and main() respectively
  2213.  
  2214.         time spent in fubar2() for calls made from fubar1() and main(), adds
  2215.         up to the total on the first line.
  2216.  
  2217.         _loop    calls=11     total=    0.96 mS
  2218.             From _main     calls=1      total=    0.96 mS (100.00%)
  2219.             From _loop     calls=1      total=    0.04 mS (  4.65%)
  2220.             From _loop     calls=1      total=    0.13 mS ( 13.95%)
  2221.             From _loop     calls=1      total=    0.22 mS ( 23.25%)
  2222.             From _loop     calls=1      total=    0.31 mS ( 32.55%)
  2223.             From _loop     calls=1      total=    0.40 mS ( 41.86%)
  2224.             From _loop     calls=1      total=    0.49 mS ( 51.16%)
  2225.             From _loop     calls=1      total=    0.60 mS ( 62.79%)
  2226.             From _loop     calls=1      total=    0.69 mS ( 72.09%)
  2227.             From _loop     calls=1      total=    0.78 mS ( 81.39%)
  2228.         From _loop     calls=1      total=    0.87 mS ( 90.69%)
  2229.  
  2230.         **** COMBINED CALL TREE ****
  2231.  
  2232.         Top line contains the same information from table 1
  2233.  
  2234.         _main    calls=1     tot=  539.53 (100.00)  loc=   10.37 (  1.92)
  2235.             _fubar1 calls=101    tot=  517.45 ( 95.90)  loc=  507.75 ( 94.10)
  2236.             _fubar2 calls=101    tot=   10.75 (  1.99)  loc=   10.75 (  1.99)
  2237.             _loop   calls=1    tot=    0.96 (  0.17)  loc=    0.08 (  0.01)
  2238.         main() calls fubar1() 101 times, fubar1() takes 517 mS total time over
  2239.         these calls.    main() calls fubar2() directly 101 times and fubar2()
  2240.         takes 10 mS over these calls.  Note that fubar2()'s time is not the
  2241.         same as in table 1 because only those calls made from main() are
  2242.         counted here.
  2243.  
  2244.         Percentages are relative to main()
  2245.  
  2246.         fubar1() calls fubar2() 101 times.  percentages are relative to
  2247.         fubar1()'s total time.  Note that if you add fubar2()'s number of
  2248.         calls and total time to the fubar2() entry above you will get the
  2249.         grand total for fubar2() shown in the first table.
  2250.  
  2251.         _fubar1 calls=101   tot=  517.45 (100.00)  loc=  507.75 ( 98.12)
  2252.             _fubar2 calls=101    tot=    9.69 (  1.87)  loc=    9.69 (  1.87)
  2253.         
  2254.         _fubar2 calls=202   tot=   20.44 (100.00)  loc=   20.44 (100.00)
  2255.         
  2256.         _loop    calls=11    tot=    0.96 (100.00)  loc=    0.96 (100.00)
  2257.               calls=10
  2258.         The profiled data includes the entire call tree but for simplicity,
  2259.         recursive calls are simply shown as above.
  2260.  
  2261.         You can also request DPROF to print out the entire call tree.  This is
  2262.         done by adding the -call option to dprof.  Note, however, that this
  2263.         option may result in a huge amount of data printed out.  On the
  2264.         otherhand, much of the data is quite useful especially when tracing
  2265.         subroutine stacking and other things.
  2266.  
  2267.         1> dprof test -call
  2268.         
  2269.             .....
  2270.         
  2271.         **** CALL TREE ****
  2272.         
  2273.         _main    calls=1     tot=  539.53 (100.00)  loc=   10.37 (  1.92) {
  2274.             _fubar1 calls=101    tot=  517.45 ( 95.90)  loc=  507.75 ( 94.10) {
  2275.             _fubar2 calls=101   tot=    9.69 (  1.79)  loc=    9.69 (  1.79)
  2276.             }
  2277.             _fubar2 calls=101    tot=   10.75 (  1.99)  loc=   10.75 (  1.99)
  2278.             _loop   calls=1    tot=    0.96 (  0.17)  loc=    0.08 (  0.01) {
  2279.             _loop    calls=1     tot=    0.87 (  0.16)  loc=    0.08 (  0.01) {
  2280.                 _loop   calls=1    tot=    0.78 (  0.14)  loc=    0.08 (  0.01) {
  2281.                 _loop    calls=1     tot=    0.69 (  0.12)  loc=    0.08 (  0.01) {
  2282.                     _loop   calls=1    tot=    0.60 (  0.11)  loc=    0.11 (  0.02) {
  2283.                     _loop    calls=1     tot=    0.49 (  0.09)  loc=    0.08 (  0.01) {
  2284.                         _loop   calls=1    tot=    0.40 (  0.07)  loc=    0.08 (  0.01) {
  2285.                         _loop    calls=1     tot=    0.31 (  0.05)  loc=    0.08 (  0.01) {
  2286.                             _loop   calls=1    tot=    0.22 (  0.04)  loc=    0.08 (  0.01) {
  2287.                             _loop    calls=1     tot=    0.13 (  0.02)  loc=    0.08 (  0.01) {
  2288.                                 _loop   calls=1    tot=    0.04 (  0.00)  loc=    0.04 (  0.00)
  2289.                             }
  2290.                             }
  2291.                         }
  2292.                         }
  2293.                     }
  2294.                     }
  2295.                 }
  2296.                 }
  2297.             }
  2298.             }
  2299.         }
  2300.  
  2301.  
  2302. dice/dsearch                                                    dice/dsearch
  2303.  
  2304.     NAME
  2305.         Search for string in a file
  2306.  
  2307.     SYNOPSIS
  2308.         Dsearch string files
  2309.  
  2310.     DESCRIPTION
  2311.         Dsearch is used for searching for a string in a series of files
  2312.  
  2313.  
  2314. dice/du                                                              dice/du
  2315.  
  2316.     NAME
  2317.         Show Disk usage
  2318.  
  2319.     SYNOPSIS
  2320.         du volume
  2321.  
  2322.     DESCRIPTION
  2323.         returns disk space used by a directory or volume
  2324.  
  2325.  
  2326. dice/dupdate                                                    dice/dupdate
  2327.  
  2328.     NAME
  2329.         Distribution Maker
  2330.  
  2331.     SYNOPSIS
  2332.         DUPDATE dist-file dest-dir [options] [DISTFILE distfilename]
  2333.  
  2334.     DESCRIPTION
  2335.         DUPDATE is a program that creates distributions.  It creates an exact
  2336.         duplicate of the source directory tree in the destination with
  2337.         modifications according to control files in the tree.  DUPDATE deletes
  2338.         files in the destination tree that do not exist in the source and
  2339.         updates files from the source into the destination tree that have been
  2340.         modified since the last dupdate (or copies them fresh if they do not
  2341.         exist).
  2342.  
  2343.      FORCE  DUPDATE will not ask permission to copy a fresh file
  2344.  
  2345.      QUIET  DUPDATE will not display verbose output
  2346.  
  2347.      NODEL  DUPDATE will not delete files in the destination that do not exist
  2348.             in the source.
  2349.  
  2350.  DISTFILE file
  2351.             Specify alternate control file that 'modifies' the dist update,
  2352.             default is .DistFiles
  2353.  
  2354.             If a file ".DistFiles" exists in any directory of the source tree,
  2355.             updating of the destination is modified according to the file. 
  2356.             This is a text file which may specify additional files/directories
  2357.             to add to the destination directory (pulled from other random
  2358.             places), files and directories NOT to include in the destination
  2359.             tree, or a list of specific files to include (where files not
  2360.             listed are not included).
  2361.  
  2362.             By using the DISTFILE file option you can generate different
  2363.             distributions for different purposes all based in the same source
  2364.             tree.  For example, I have a DISTFILE set to create the registered
  2365.             and non-registered DICE distributions and other DISTFILE files
  2366.             (using different names) to create the three floppies in the
  2367.             registered distribution.
  2368.  
  2369.             In the first format, if the ONLY keyword is specified after the
  2370.             first file name only these files / sub-directories will be
  2371.             included from this directory.  No other files will be copied
  2372.  
  2373.             file_or_dir_name ONLY
  2374.             file_or_dir_name
  2375.             file_or_dir_name
  2376.             file_or_dir_name
  2377.             file_or_dir_name
  2378.  
  2379.             The second format allows files/directories to be made part of the
  2380.             destination tree that do not necessarily exist in the current
  2381.             directory. Additionally, specific files/directories that do exist
  2382.             in the current directory can be excluded.  Any file/dir not
  2383.             explicitly unincluded using the 'no' keyword will be copied.
  2384.  
  2385.             file_or_dir_path
  2386.             file_or_dir_path
  2387.             file_or_dir_path
  2388.             no file_or_dir_path
  2389.             no file_or_dir_path
  2390.             file_or_dir_path
  2391.  
  2392.  
  2393. dice/enforcer                                                  dice/enforcer
  2394.  
  2395.     NAME
  2396.         Locate hidden bugs in programs (MMU).
  2397.  
  2398.     SYNOPSIS
  2399.         ENFORCER [on|off|quiet|fprotect]
  2400.  
  2401.     DESCRIPTION
  2402.         Enforcer uses the powerful features of a Memory Management Unit (MMU)
  2403.         to detect bugs in programs.  Often, the bugs detected by Enforcer are
  2404.         difficult or impossible to locate by any other method.
  2405.  
  2406.         :: NOTE: Regular use of Enforcer is highly recommended for all
  2407.         :: programmers. For commercial products, use of Enforcer is virtually
  2408.         :: mandantory; commercial products must work on a wide variety of
  2409.         :: machines, and peacfully coexist with a wide varriety of other
  2410.         :: programs.  Most magazine reviewers test with Enforcer.
  2411.  
  2412.         on  Turn Enforcer on.  This option is the default.
  2413.  
  2414.             :: NOTE: With Enforcer enabled, an Amiga 3000 will always
  2415.             :: cold-boot. This causes Kickstart to be reloaded from disk, and
  2416.             :: will wipe out some "recoverable" RAM disks.  To eliminate this
  2417.             :: problem, turn Enforcer off before rebooting.
  2418.  
  2419.        off  Disable Enforcer, returning the system to the unprotected state.
  2420.  
  2421.      quiet  Turn Enforcer on, but ignore all protection violations.
  2422.  
  2423.   fprotect  Turn Enforcer on, and write-protect the memory range
  2424.             0xF0000-0xF7FFFF. This option is only useful for internal
  2425.             development by Commodore-Amiga.
  2426.  
  2427.     REQUIREMENTS
  2428.         Enforcer requires a machine equiped with a either a 68030 processor,
  2429.         or a 68851 Memory Management Unit (MMU).  Any Commodore-Amiga A3000 or
  2430.         A2500 series computer will work, as will any computer with an A2620 or
  2431.         A2630 plug-in card. Many third-party processor accelerator will also
  2432.         work.
  2433.  
  2434.         For use under Kickstart 1.3, Enforcer requires the Commodore patch
  2435.         program, SetPatch, Version 1.38 or later.  Enforcer detects and
  2436.         ignores many of the bugs in 1.3 Kickstart.  However, due to these
  2437.         bugs, use of Enforcer under 1.3 is discouraged.
  2438.  
  2439.             REMOTE OPERATION
  2440.         Enforcer writes directly to the serial port hardware, at 9600 baud or
  2441.         at the last baud rate used on the port.  A modem can substitute for an
  2442.         external terminal in some cases.  Run a modem program and configure
  2443.         the modem to echo any characters.  Most Hayes compatible modems will
  2444.         echo while waiting for an "AT" command.
  2445.  
  2446.         From the remote system, the following keystrokes control Enforcer:
  2447.  
  2448.         ^S  Pause output.  You may need to press this key more than once.
  2449.  
  2450.         ^Q  Resume after pause.
  2451.  
  2452.         ^X  When paused, press ^X to suspect Enforcer reporting.  Press ^Q to
  2453.             resume.
  2454.  
  2455.     EXAMPLE
  2456.         The program "lawbreaker" has written value 0xDDDD0000 to memory
  2457.         location 0xC0EDBABE.  See chapter [TBA] for full details.
  2458.  
  2459.     SEE ALSO
  2460.         [TBA]
  2461.  
  2462.  
  2463. dice/expand                                                      dice/expand
  2464.  
  2465.     NAME
  2466.         expand wildcards
  2467.  
  2468.     SYNOPSIS
  2469.         expand wildcards
  2470.  
  2471.     DESCRIPTION
  2472.         Expand is useful
  2473.  
  2474.  
  2475. dice/fdtolib                                                    dice/fdtolib
  2476.  
  2477.     NAME
  2478.         Create Link Libraries from .FD files
  2479.  
  2480.     SYNOPSIS
  2481.         FDTOLIB files/wildcard.fd [-h hdrfile] -o libname [-mr] [-mD]
  2482.  
  2483.     DESCRIPTION
  2484.         FDTOLIB will create an amiga standard library out of specified .FD
  2485.         files (for example, you can generate most of amiga.lib by using the
  2486.         .FD files on your 1.3 Extras disk).
  2487.  
  2488.         Basically, FDTOLIB will generate one of four types of libraries:
  2489.  
  2490.         Option, Library Type
  2491.  
  2492.         default, small-data model
  2493.  
  2494.         -mD, large-data model
  2495.  
  2496.         -mr, small-data model + DICE registered parameters entry pts
  2497.  
  2498.         -mr -mD, large-data model + DICE registered parameters entry pts
  2499.  
  2500.         If -mr is used suitable prototypes must be specified with the -h
  2501.         option. In this case, FDTOLIB will run DCC with a special option to
  2502.         have it generate a register-specification file for it to match up
  2503.         again the .FD files.
  2504.  
  2505.         FDTOLIB then proceeds to scan the .FD files, creating temporary
  2506.         assembly files in T: and assembling them with DAS, then appending them
  2507.         to
  2508.  
  2509.         the output library and deleting the scratch files.  This step occurs
  2510.         for each function in each .FD files.
  2511.  
  2512.         (For faster operation, you will want to make DAS resident for the
  2513.         duration)
  2514.  
  2515.         If -mr was specified, FDTOLIB only generates library entries for those
  2516.         routines for which a prototype exists.  At the end of the run FDTOLIB
  2517.         will report any routines which existed in the .FD files but did not
  2518.         have a prototype.
  2519.  
  2520.         files/wildcard.fd specifies one or more files and/or AmigaDOS
  2521.         wildcarding that represents the .FD files that are to be processed
  2522.         into a library
  2523.  
  2524.  -h hdrfile
  2525.             hdrfile is a .H files that #include's all prototypes associated
  2526.             with the .FD files.  It is only used if the -mr option is
  2527.             specified
  2528.  
  2529.  -o libname
  2530.             specify output library name
  2531.  
  2532.        -mr  specify that a REGISTERED call interface library is to be
  2533.             generated (for DICE -m[r,R,RR] options), else generates a normal
  2534.             stack-args interface library.
  2535.  
  2536.        -mD  specify large-data model, else small-data model
  2537.  
  2538.  -I include-dir
  2539.             passed to DCC
  2540.  
  2541.  -p prefix  Set prefix (currently only for standard generation, doesn't work
  2542.             with -mr).  The default is a single underscore`_'.  This option is
  2543.             normally used to generate _hyper_ tags for dynamic.library
  2544.  
  2545.      -prof  Generate profiling code for the tags.  This will cause all library
  2546.             calls to be profiled when the program that links with this library
  2547.             is run.
  2548.  
  2549.  -auto library
  2550.             Generate auto-init code for library after the tags.  library is
  2551.             the name of the shared library.  For example, -auto fubar.library
  2552.  
  2553.  -AUTO library
  2554.             Generate ONLY auto-init code for library (do not generate tags)
  2555.  
  2556.  
  2557. dice/flush                                                        dice/flush
  2558.  
  2559.     NAME
  2560.         Flush Memory, Libraries, and Devices
  2561.  
  2562.     SYNOPSIS
  2563.         flush
  2564.  
  2565.     DESCRIPTION
  2566.         flush is used to force items out of memory
  2567.  
  2568.  
  2569. dice/head                                                          dice/head
  2570.  
  2571.     NAME
  2572.         Display start of a file
  2573.  
  2574.     SYNOPSIS
  2575.         head file
  2576.  
  2577.     DESCRIPTION
  2578.         Head is useful for seeing the first few lines in a file
  2579.  
  2580.     SEE ALSO
  2581.         tail
  2582.  
  2583.  
  2584. dice/ident                                                        dice/ident
  2585.  
  2586.     NAME
  2587.         Identify Files
  2588.  
  2589.     SYNOPSIS
  2590.         ident [ -q ] [ file ...  ]
  2591.  
  2592.     DESCRIPTION
  2593.         Ident searches the named files or, if no file name appears, the
  2594.         standard input for all occurrences of the pattern $keyword:...$, where
  2595.         keyword is one of
  2596.  
  2597.         Author
  2598.         Date
  2599.         Header
  2600.         Id
  2601.         Locker
  2602.         Log
  2603.         Revision
  2604.         RCSfile
  2605.         Source
  2606.         State
  2607.  
  2608.         These patterns are normally inserted automatically by the RCS command
  2609.         co, but can also be inserted manually.  The option -q suppresses the
  2610.         warning given if there are no patterns in a file.
  2611.  
  2612.         Ident works on text files as well as object files and dumps.  For
  2613.         example, if the C program in file f.c contains
  2614.  
  2615.         char rcsid[] = "$Header: Work:Devel/oi/diceman/RCS/chap08.txt,v 1.2
  2616.         92/06/09 06:40:43 jtoebes Exp $";
  2617.  
  2618.         and f.c is compiled into f.o, then the command
  2619.  
  2620.         ident f.c f.o
  2621.  
  2622.         will print
  2623.  
  2624.         f.c: $Header: Work:Devel/oi/diceman/RCS/chap08.txt,v 1.2 92/06/09
  2625.          06:40:43 jtoebes Exp $
  2626.         f.o: $Header: Work:Devel/oi/diceman/RCS/chap08.txt,v 1.2 92/06/09
  2627.         06:40:43 jtoebes Exp $
  2628.  
  2629.     SEE ALSO
  2630.         ci, co, rcs, rcsdiff, rcsintro, rcsmerge, rlog
  2631.  
  2632.  
  2633. dice/istrip                                                      dice/istrip
  2634.  
  2635.     NAME
  2636.         Strip Comments From Include Files
  2637.  
  2638.     SYNOPSIS
  2639.         ISTRIP destprefix wildcards
  2640.  
  2641.     DESCRIPTION
  2642.         ISTRIP will strip comments and extranious whitespace from all files
  2643.         specified by wildcards and create an output file under the same name
  2644.         prefixed by destprefix.
  2645.  
  2646.         ISTRIP is very stupid in that it will not create the destination
  2647.         directory hierarchy.  The COPY command in the example below basically
  2648.         does that for us, the copied files are extranious and overwritten when
  2649.         ISTRIP is run.
  2650.  
  2651.         ISTRIP is useful mainly for developers who obtain later versions of
  2652.         the commented Amiga includes and want to create an uncommented version
  2653.         (The uncommented includes are much smaller yielding faster
  2654.         compilation).
  2655.  
  2656.     EXAMPLE
  2657.         (contrived)
  2658.  
  2659.         1> cd dinclude:
  2660.         1> copy amiga13 ram:amiga13 ALL QUIET
  2661.         1> istrip ram: amiga13/#?/#?
  2662.  
  2663.  
  2664. dice/lbmake                                                      dice/lbmake
  2665.  
  2666.     NAME
  2667.         Create Link Library
  2668.  
  2669.     SYNOPSIS
  2670.         lbmake files
  2671.  
  2672.     DESCRIPTION
  2673.         lbmake is used to
  2674.  
  2675.     SEE ALSO
  2676.         libmake
  2677.  
  2678.  
  2679. dice/lharc                                                        dice/lharc
  2680.  
  2681.     NAME
  2682.         Archive Utility
  2683.  
  2684.     SYNOPSIS
  2685.         Lharc [switches] Command  Archive  [dest path] [file patterns]
  2686.  
  2687.     DESCRIPTION
  2688.         LHARC is used to build archives of multiple files, compressing them in
  2689.         the process.
  2690.  
  2691.     COMMANDS
  2692.         Command can be any of the following (case is not significant):
  2693.  
  2694.       e
  2695.     x  Extract files from archive.  If you specify some file names or
  2696.             patterns only those files satisfying the patterns are extracted,
  2697.             otherwise all the files in the archive are extracted.  While
  2698.             extracting files, Lharc checks if a file by the same name already
  2699.             exsists in the destination directory and prompts you before
  2700.             overwriting the old file with the extracted one (unless you
  2701.             specified the -m switch) By default, if the files have a path name
  2702.             stored in the archive, they are extracted with their path and
  2703.             needed directories are automatically created; use the -x0 switch
  2704.             to ignore path names.  See below under dest path for a discussion
  2705.             on where the extracted files are stored.
  2706.  
  2707.          l  show archives contents Displays the names of the files in an
  2708.             archive along with their date, time, CRC, compression type,
  2709.             original lenght and compressed lenght.  If the -x switch is
  2710.             specified file names are listed complete with their path (if
  2711.             present in the archive), otherwise only the name of the files is
  2712.             listed.  The l command won't list the comments (filenotes) that
  2713.             may be assiciated with a file: use the v command to see them, too.
  2714.  
  2715.          v  Same as l, but default is to display full pathnames: i.e.  the v
  2716.             command is equivalent to the l command with the -x switch; on the
  2717.             other hand the 'l' command is equivalent to the v command with the
  2718.             -x0 switch.  Moreover v will also show any filenote (i.e. 
  2719.             comment) associated with the files; filenotes, if present, are
  2720.             listed on a separate line preceded by a colon (i.e.  in the same
  2721.             format used by the AmigaDOS list command).
  2722.  
  2723.          p  extract and print files to screen.  This is the same as e and x,
  2724.             but extracted files are sent to stdout
  2725.  
  2726.          t  test archive integrity Checks CRCs and checksums to ensure that
  2727.             the archive is not corrupted.  Lharc will test all the files on
  2728.             the archive, one after each other, printing "OK" to the right of
  2729.             the file names which are OK and "WARNING: CRC check failed" to the
  2730.             right of file names that are corrupted.  At the end of the test
  2731.             the message "Operation successful" means that all the files tested
  2732.             were OK, while the message "Operation not totally successful"
  2733.             means that some files in the archive were corrupted (so you will
  2734.             know of a corrupted file even if the warning message relating to
  2735.             that file has scrolled away on the screen)
  2736.  
  2737.          a  create archives or add to existing archives Files are stored in
  2738.             alphabetical order, unless you change this with the -S switch.
  2739.             Note however that sorting only applies to the files beeing added
  2740.             in the current session, i.e.  if you add files to an existing
  2741.             archive containing other files, the new files will be stored, in
  2742.             alphabetical order, AT THE END of the archive: old and new files
  2743.             won't be intermixed to preserve global alphabetical order.  If you
  2744.             try to archive a file and a file by the same name already exists
  2745.             in the archive the file will not be added and a message will be
  2746.             printed on the screen to inform you.  By default only file names
  2747.             are stored in the archive, use the -x switch to store file names
  2748.             complete with their paths.  Also, by default file attributes are
  2749.             not stored, use the -a switch to obtain this.
  2750.  
  2751.          m  move files into archivs Same as add, but deletes original files
  2752.             after archiving them
  2753.  
  2754.          d  delete files from archives You can delete from an archive a
  2755.             maximum of 150 files at a time.
  2756.  
  2757.          u  update files in archives Same as with the a command.  However, if
  2758.             a file already exists in the archive, LHarc will check its time
  2759.             stamp and will keep the newer one and ignore the older one.
  2760.  
  2761.          f  freshen files in archives. Replaces a file in the archive with the
  2762.             newer one only if a file with the same name already exists in the
  2763.             archive.  Otherwise, no action is taken.
  2764.  
  2765.    Archive  is the name (eventually preceded by a path) of the archive you
  2766.             want to work on.  If no extension is specified the default
  2767.             extension .LZH is used.  With the 'l' (or 'v'), 'e' (or 'x'), 'p',
  2768.             't' and 'a' commands you can work on multiple archives by using
  2769.             wildcards (see 'file patterns' below for a list of accepted
  2770.             wildcards).  For example
  2771.  
  2772.             lharc v *.LZH
  2773.  
  2774.             will show the contents of all the archives in the current
  2775.             directory, while
  2776.  
  2777.             lharc x *.LZH *.c
  2778.  
  2779.             will extract all the C source files contained in all the archives
  2780.             in the current directory.
  2781.  
  2782.  dest path  This parameter is significant only with the x (or e) command.  It
  2783.             tells where to put the extracted files; if not specified,
  2784.             extracted files will go to the current directory.  Please note
  2785.             that this paramenter must always end with '/' or ':' otherwise it
  2786.             will not be recognized as such and will be considered as one of
  2787.             the file patterns.
  2788.  
  2789.             If the path specified by dest path (or equivalently the path
  2790.             stored in the archive) does not already exist, you will be
  2791.             prompted if you want new directories to be automatically created
  2792.             (unless you specified the -m switch, in which case directories
  2793.             will be created without any prompt).
  2794.  
  2795.  file patterns
  2796.             An optional number of file names or file patterns.  They indicate
  2797.             which files to extract/compress/list/delete, ecc.  Accepted wild
  2798.             cards are the standard AmigaDOS '#' and '?' plus the '*' which is
  2799.             a synonym of '#?'.  Since however the asterisk is a valid
  2800.             character in AmigaDOS file names,  '**' acts as an escape.  So if
  2801.             you want to refer to a file name containing an asterisk just
  2802.             double the asterisk in the file name.  Example: *.c is equivalent
  2803.             to #?.c and refers to all the files ending with .c, while my**file
  2804.             refers to the file my*file.
  2805.  
  2806.     SWITCHES
  2807.         A switch is composed by a leading '-' followed by one letter; unlike
  2808.         command, switches are case sensitive.  An important point is that if
  2809.         you want to specify more than one switch, every switch must be
  2810.         preceded by its own dash, i.e.  to activate the x and m switches you
  2811.         must enter -x -m and NOT -xm.  Any options to the switches must follow
  2812.         the switch letter immediately with no intervening spaces.
  2813.  
  2814.         You can store your favourite switch configuration in an environment
  2815.         variable called LHARC so that you don't have to type them every time. 
  2816.         All the switches that don't take a parameter can be followed by a 0
  2817.         which turns off the function, while the switch alone or the switch
  2818.          followed by a 1 turns the function on:
  2819.         i.e.       -x means "use extended file names"
  2820.         while -x0 means "don't use them".
  2821.  
  2822.         You can override the default settings or the settings you specified in
  2823.         the environment variable LHARC.  Default value for every switch is
  2824.         off, except for the -a switch which is on with all the commands and
  2825.         for the -x switch which is by default on with the x e d t and v
  2826.         commands and off with the other commands.
  2827.  
  2828.         -p  pause after loading
  2829.  
  2830.             Causes Lharc to wait for the user to press RETURN before executing
  2831.             a command. This allows floppy disk users to swap disks after
  2832.             loading Lharc.
  2833.  
  2834.         -m  no message for query
  2835.  
  2836.             Suppresses all the queries Lharc normally issues before
  2837.             overwriting existing files or before creating new directories If
  2838.             you specify this switch Lharc will behave as if you choose the
  2839.             default action (indicated by an uppercase letter) in response to
  2840.             all the questions.  This switch also disables autoshowing of files
  2841.             (see Autoshow files below)
  2842.  
  2843.         -x  use extended file names
  2844.  
  2845.             By default, LHarc stores only the file names of files and
  2846.             disregards the names of the directories in which they reside. 
  2847.             This switch, used with the a command, tells LHarc to extend all
  2848.             file names with directory names; with the x e d t and v commands
  2849.             the -x switch is automatically turned on: use -x0 if you want to
  2850.             turn it off thus ignoring pathnames with these commands.
  2851.  
  2852.         -n  no progress indicator
  2853.  
  2854.             Suppresses the display of the number of bytes beeing processed
  2855.             during compression or decompression.  May be useful if you
  2856.             redirect to a file the output of Lharc.
  2857.  
  2858.      -wdir  set work directory
  2859.  
  2860.             Use this switch to choose your own directory for temporary files. 
  2861.             See Temporary files for a discussion on where temporary files are
  2862.             stored in the absence of this switch.
  2863.  
  2864.  -Ppriority
  2865.             set priority (note that this is uppercase P)
  2866.  
  2867.             Use this switch to set the priority with which Lharc will be
  2868.             executed. Priority must be in the range -5..+5.  By default Lharc
  2869.             is excuted with the same priority of the task that invoked it;
  2870.             using this switch will set the new priority immediately after
  2871.             loading and will set back the priority to the original value
  2872.             immediately after terminating.
  2873.  
  2874.             If you want to do something else with your Amiga, for example
  2875.             editing a letter, while Lharc is compressing a long file, you
  2876.             should Lharc's priority to one less than that of the other
  2877.             program, i.e.  if you started your editor with the usual priority
  2878.             of zero then invoke Lharc with the -P-1 switch to set its priority
  2879.             to -1
  2880.  
  2881.         -a  consider file attributes
  2882.  
  2883.             Lharc can ignore file attributes (i.e.  the flags indicating
  2884.             protection from deletion, and so on) for maximum compatibility
  2885.             with the MSDOS version: in other words it can store files with an
  2886.             attribute bit pattern which is suitable for MSDOS machines and,
  2887.             during extraction, ignore the attributes stored in the archives,
  2888.             setting the attributes of the extracted files to the usual
  2889.             '----rwed'.
  2890.  
  2891.             Alternatively Lharc can preserve the protection bits by storing
  2892.             them in the archive and then restoring them during extraction.  In
  2893.             Lharc version 1.3 and higher, this switch is by default on, i.e. 
  2894.             file protection bits will be preserved: use -a0 to turn it of to
  2895.             achieve full MSDOS compatibility.  Remember that, to effectively
  2896.             preserve file attributes, you must use the same setting for this
  2897.             switch both during compression and during extraction.
  2898.  
  2899.             Of course AmigaDOS file attributes are meaningless to MSDOS and
  2900.             vice-versa; so extract files with the -a switch only if you are
  2901.             sure that they contain AmigaDOS file attributes and similarly
  2902.             compress files with the -a switch only if you are sure that the
  2903.             archive will be unpacked only by Amigas and not by MSDOS machines.
  2904.             (Anyway no harm is done if this rule is not respected: extracted
  2905.             files will simply have strange attributes)
  2906.  
  2907.         -u  convert file names to uppercase
  2908.  
  2909.             By default Lharc stores file names/paths with thier original case,
  2910.             if you use this switch they will be converted to uppercase.  See
  2911.             Compatibility for a possible use of this switch.
  2912.  
  2913.         -r  recursively collect files
  2914.  
  2915.             This switch instructs Lharc to search for files matching the
  2916.             specified patterns not only in the specified directories, but also
  2917.             in all the subdirectories that may be found in the specified
  2918.             directories.  For example:
  2919.  
  2920.             Lharc -r a archive.lzh df1:source/*.c
  2921.  
  2922.             will search for files whose name ends with ".c" in "df1:source/"
  2923.             and in all the subdirectories that may be contained in the
  2924.             "df1:source" directory.
  2925.  
  2926.             Another example:
  2927.  
  2928.             Lharc -r a archive.lzh df1:*
  2929.  
  2930.             will archive the entire disk in drive df1:, including all its
  2931.             subdirectories.
  2932.  
  2933.             When you specify the -r switch, files are always stored with their
  2934.             path name, i.e.  the -r switch automatically turns on the -x
  2935.             switch, too.
  2936.  
  2937.        -re  recursively collect files and store empty directories
  2938.  
  2939.             This works just like the -r option, but also gathers empty
  2940.             directories.  By an empty directory, we mean directories which are
  2941.             actually empty or which contain no files matching the patterns
  2942.             specified on the command line.  This option allows you to
  2943.             perfectly re-create a directory tree, but remember that archives
  2944.             containing empty dirs are NOT compatible with MSDOS-Lharc 1.13;
  2945.             so, use -re only if you are sure that the archive you are
  2946.             producing will be unpacked on Amiga machines only.
  2947.  
  2948.  -Scriteria
  2949.             Set sorting criteria (note that this is an UPPLERCASE S)
  2950.  
  2951.             This switch sets the sort criterium for files being added to
  2952.             archives. criteria is specified by up to four characters
  2953.  
  2954.             Position, Char, Meaning
  2955.  
  2956.             First Character, 0, Don't sort files
  2957.  
  2958.             ^, a, Alphabetical sort [default]
  2959.  
  2960.             ^, c, Chronological sort
  2961.  
  2962.             Second Character, a, Ascending order [default]
  2963.  
  2964.             ^, d, Descending order
  2965.  
  2966.             Third Character, i, Case insensitive alpha-sorting [default]
  2967.  
  2968.             ^, s, Case sensitive alpha-sorting
  2969.  
  2970.             Fourth Character, l, Local sorting [default]
  2971.  
  2972.             ^, g, Global sorting
  2973.  
  2974.             The -S0 option is useful if you want to create an archive in which
  2975.             files appear in a given order: the -S0 switch tells Lharc to add
  2976.             files in the same order as they were specified in the command line
  2977.             (or in the '-i' file).
  2978.  
  2979.     GLOBAL/LOCAL
  2980.     SORTING
  2981.         global sorting means that files will be stored in strict alphabetical
  2982.         or chronological order; local sorting means that sorting will be local
  2983.         to each subdirectory with more 'nested' subdirectories pushed at the
  2984.         end of the archive.  As an example, look at the following lists of
  2985.         files: the left column is sorted with alpha-global sorting, the right
  2986.         one is sorted with alpha-local sorting
  2987.  
  2988.         GLOBAL SORTING, LOCAL SORTING
  2989.  
  2990.         Announcement, Announcement
  2991.  
  2992.         README, README
  2993.  
  2994.         include/common.h, include/common.h
  2995.  
  2996.         include/foo/abc.h, include/global.h
  2997.  
  2998.         include/foo/rexx/rexx.h, include/rexxbind.h
  2999.  
  3000.         include/foo/rexx/rexxglue.h, l/xyzzy-handler
  3001.  
  3002.         include/global.h, lib/ps.library
  3003.  
  3004.         include/old/foo/abc.h, s/.xyzzyrc
  3005.  
  3006.         include/old/poof/xyz.h, s/add-2-startup-sequence
  3007.  
  3008.         include/poof/poof.h, src/Makefile
  3009.  
  3010.         include/poof/xyz.h, src/foo.c
  3011.  
  3012.         include/rexxbind.h, src/poof.c
  3013.  
  3014.         include/xyzzy/incl1.h, src/xyzzy.c
  3015.  
  3016.         include/xyzzy/incl2.h, src/zot.c
  3017.  
  3018.         include/xyzzy/incl3.h, utils/help l/xyzzy-handler
  3019.  
  3020.         utils/more lib/1.3/foo.library, include/foo/abc.h
  3021.  
  3022.         lib/1.3/old/foo.library, include/poof/poof.h
  3023.  
  3024.         lib/2.0/foo.library, include/poof/xyz.h
  3025.  
  3026.         lib/ps.library, include/xyzzy/incl1.h
  3027.  
  3028.         s/.xyzzyrc, include/xyzzy/incl2.h
  3029.  
  3030.         s/add-2-startup-sequence, include/xyzzy/incl3.h
  3031.  
  3032.         src/Makefile, lib/1.3/foo.library
  3033.  
  3034.         src/foo.c, lib/2.0/foo.library
  3035.  
  3036.         src/old/poof.c, src/old/poof.c
  3037.  
  3038.         src/poof.c, include/foo/rexx/rexx.h
  3039.  
  3040.         src/xyzzy.c, include/foo/rexx/rexxglue.h
  3041.  
  3042.         src/zot.c, include/old/foo/abc.h
  3043.  
  3044.         utils/help, include/old/poof/xyz.h
  3045.  
  3046.         utils/more, lib/1.3/old/foo.library
  3047.  
  3048.         Some common settings that you may use:
  3049.  
  3050.         Option, Meaning
  3051.  
  3052.         -Scd, Sort chronologically in descending order
  3053.  
  3054.         -Sc
  3055.         -Sca, Sort chronologically in ascending order.
  3056.  
  3057.         -S0, Don't sort at all
  3058.  
  3059.         -Sads, Sort alphabetically in descending order (case sensitive)
  3060.  
  3061.         -Saail, Sort alphabetically in ascending order; sorting will be
  3062.         case-insensitive and will be local to each subdirectory. This is also
  3063.         the default action which is taken if you don't specify this switch.
  3064.  
  3065.     -bsize  Set I/O buffer size
  3066.  
  3067.             Big I/O buffers can considerably speed up some operations of Lharc
  3068.             (espacially with hard disks). However if you are low on memory you
  3069.             may prefer to use small I/O buffers.  This switch lets you set the
  3070.             amount of memory that Lharc will use as an I/O buffer.  size is
  3071.             given in kilobytes, e.g.  -b20 tells Lharc to use 20 kbytes of
  3072.             memory for I/O buffers.  Any number between 6 and 37 is valid,
  3073.             default is using 11 Kbytes.  if you are low on memory you can
  3074.             lower this amount, but if you have plenty of memory I suggest that
  3075.             you rise it.  This option is a good candidate for storing in your
  3076.             LHARC environment variable.
  3077.  
  3078.         -f  ignore filenotes
  3079.  
  3080.             By default Lharc archives files complete with their comment
  3081.             (filenote).  If you set this switch, filenotes won't be stored in
  3082.             archives and files beeing extracted won't have any filenote even
  3083.             if it was present in the archive.  There is no compatibility
  3084.             problem, but if you are not interested in filenotes you may set
  3085.             this switch to reduce the archive size (filenotes are stored in
  3086.             uncompressed form, so if you have long filenotes they can increase
  3087.             the size of the archive).
  3088.  
  3089.         -d  set archive's datestamp
  3090.  
  3091.             By default archives created or updated by Lharc will have a
  3092.             datestamp corresponding to the date of creation of the archive. 
  3093.             If you set this switch, on the contrary, archives created or
  3094.             updated by Lharc will have the same date as the newest file
  3095.             contained in the archive.
  3096.  
  3097.         -c  confirm files
  3098.  
  3099.             If this switch is set, Lharc will ask you for confirmation before
  3100.             archiving or extracting a file.  This allows you to specify a
  3101.             large set of files through the use of wild-cards and then select
  3102.             which of them to consider in an interactive way.  If you for
  3103.             example typed:
  3104.  
  3105.             Lharc -c a test.lzh *.c
  3106.  
  3107.             all the files ending with .c in the current directory will be
  3108.             presented to you with the message:
  3109.  
  3110.             "Archive file xxx.c? [(Y)es, (n)o, (a)ll, n(o)ne]"
  3111.  
  3112.             You have four alternatives: to choose between them just type the
  3113.             letter indicated in parenthesis and press return.  The `(Y)' is
  3114.             printed in uppercase to remember you that this is the default
  3115.             action which is taken if you simply press return.  The meanings of
  3116.             the four alternatives are:
  3117.  
  3118.             Choice, Action
  3119.  
  3120.             yes, archive the file
  3121.  
  3122.             no, don't archive the file
  3123.  
  3124.             all, archive this file and all the following files without asking
  3125.             anymore for confirmation.
  3126.  
  3127.             none, don't archive this file nor any of the following files
  3128.  
  3129.             This switch is ignored if the -m switch is active.
  3130.  
  3131.     -ifile  read input from a file
  3132.  
  3133.             This switch tells Lharc to read the list of files to act upon from
  3134.             file.  If the -i switch is specified alone (i.e.  without a
  3135.             filename) the file list is read from stdin.  For example:
  3136.  
  3137.             Lharc -idf1:list a foo.LZH
  3138.  
  3139.             will add all the files specified in the df1:list file.  This file
  3140.             can contain ordinary file names or file patterns to be added, each
  3141.             on a separate line: a file name is assumed to be terminated by a
  3142.             space or a tab, everything on the line after the first space or
  3143.             tab is ignored. If a file name contains spaces, it must be
  3144.             enclosed in double quotes. The ability to read the list of files
  3145.             from stdin allows the use of Lharc in a pipe of comamnds, for
  3146.             example:
  3147.  
  3148.             list since today | Lharc -i a foo.lZH
  3149.  
  3150.             will archive all the files in the current directory which were
  3151.             created today.  (A shell that supports the | character is
  3152.             required) Note that you can also specify some files on the command
  3153.             line, if you want; the command:
  3154.  
  3155.             Lharc -idf1:list a foo.LZH hello.c bye.c
  3156.  
  3157.             will add the 2 files hello.c and bye.c plus all the files
  3158.             specified in the file named df1:list.  As mentioned above,
  3159.             although this is of less frequent use, you can also use the -i
  3160.             switch to supply a list of files to be extracted, printed, listed,
  3161.             ecc.  Please note that the number of filenames or patterns that
  3162.             can be specified through the -i switch is limited to about 120.
  3163.  
  3164.     EVIRONMENT
  3165.     SETTINGS
  3166.         You may set any of LHarc's default switches with the environment
  3167.         variable LHARC: So, if you, for example, want to always set the
  3168.         archive's date to that of the newest file in the archive, use the
  3169.         maximum allowed I/O buffer size and use dh0:mytemp/ as a working
  3170.         directory, you simply type:
  3171.  
  3172.         SenEnv LHARC "-wdh0:mytemp -d -b37"
  3173.  
  3174.         (don't forget the quotes)
  3175.  
  3176.         Now Lharc will behave as if you typed the above switches every time
  3177.         you invoke it.  You can insert the setenv command in your
  3178.         startup-sequence so that it's automatically executed every time you
  3179.         turn your computer on.  Of course, you can always override the default
  3180.         settings estabilished in the enviroment variable with the command
  3181.         line: for example a -d0 in the command line will override the -d found
  3182.         in the above enviromnet variable.
  3183.  
  3184.         :: NOTE: Setenv is only available in Workbench 1.3 and higher
  3185.  
  3186.  
  3187. dice/libmake                                                    dice/libmake
  3188.  
  3189.     NAME
  3190.         Library Creation Utility
  3191.  
  3192.     SYNOPSIS
  3193.         libmake file options
  3194.  
  3195.     DESCRIPTION
  3196.         Libmake is a utility that will scan a file listings sources files for
  3197.         a library, determine what is out of date, compile the out of date
  3198.         modules (compile .c modules, assemble .a modules), and JOIN the whole
  3199.         thing together in the end to create a library.  Libmake is useful for
  3200.         creating large libraries that would otherwise overflow the command
  3201.         line length limit in DMakefile.
  3202.  
  3203.         Libmake takes several arguments, some optional:
  3204.  
  3205.       file  specify the control file that contains a list of source modules,
  3206.             see below.
  3207.  
  3208.         -v  verbose operation
  3209.  
  3210.         -n  dry run (do not actually compile/assemble/join anything)
  3211.  
  3212.  -Dmacro[=def]
  3213.             specify DCPP macro, i.e.  #define equivalent to be passed to all
  3214.             compiles.
  3215.  
  3216.  -o object_dir
  3217.             specify object directory prefix, if a directory must end in '/' or
  3218.             ':', allowing both file prefixes and directory paths.
  3219.  
  3220.  -l library
  3221.             specify library output file, usually something.lib
  3222.  
  3223.     -clean  instead of compiling/assembling/join'ing the library, delete ALL
  3224.             object modules from object_dir relating to the library.
  3225.  
  3226.        -pr  pass -pr option to DCC
  3227.  
  3228.     -proto  pass -proto option to DCC
  3229.  
  3230.  -mr
  3231.     -mR
  3232.     -mRR
  3233.             specify reg-call opts to DCC (normally only -mRR is useful when
  3234.             generating fully registered libraries)
  3235.  
  3236.        -mD  pass -mD to DCC, causes DCC to use the large-data model.  Default
  3237.             is to use the small-data model
  3238.  
  3239.        -mC  pass -mC to DCC, causes DCC to use the large-code model.  Default
  3240.             is to use the small-data model
  3241.  
  3242.      -prof  pass -prof to DCC, causes profiling code to be generated for all
  3243.             the routines in the library.
  3244.  
  3245.     CONTROL FILE
  3246.         The control file is named files.something by convention, for example,
  3247.         'files.c3lib', which happens to be the control file used generate
  3248.         C*.LIB.
  3249.  
  3250.         A control file may contain blank lines, lines that begin with a
  3251.         semi-colon (comments), and lines containing a file name optionally
  3252.         preceeded by a '*'.  Here is an example:
  3253.  
  3254.         ; Full C library
  3255.         assert/assert.c
  3256.         assert/abort.c
  3257.         amiga/exit.c
  3258.         amiga/main.c
  3259.         amiga/wbmain.c
  3260.         *amiga/c.a
  3261.         *amiga/c_pi.a
  3262.         *amiga/c_pr.a
  3263.         *amiga/x.a
  3264.         amiga/config.a
  3265.  
  3266.         Lines beginning with a '*' tell LIBMAKE to compile/assemble the file
  3267.         but NOT to include the object module in the generated output library.
  3268.  
  3269.         Thus, in the above example amiga/c.a would be assembled but not made
  3270.         part of the DLIB:C.LIB
  3271.  
  3272.         Also note that the path specified for a given file is appended to the
  3273.         -o (object directory) specification.  Thus, if you were to use the
  3274.         following libmake line:
  3275.  
  3276.         1> libmake files.c3lib -o dtmp:xx/ -l dlib:xx.lib -pr -proto
  3277.  
  3278.         Then object modules would be created as follows:
  3279.  
  3280.         DTMP:XX/assert/assert.o
  3281.         DTMP:XX/assert/abort.o
  3282.         DTMP:XX/amiga/exit.o
  3283.         etc..
  3284.  
  3285.         You probably want to pre-create the directory structure required.
  3286.         Please refer to the library source archive for examples (no less than
  3287.         DMakefile's calling libmake to regenerate every single DICE library
  3288.         that exists!)
  3289.  
  3290.     NAMING
  3291.     CONVENTIONS
  3292.         In order to simplify the process, libmake makes assumptions about the
  3293.         type of file based on the extension.
  3294.  
  3295.         Extension, Libmake Action
  3296.  
  3297.         .a, Assemble with DAS
  3298.  
  3299.         .a68, Assemble with A68K
  3300.  
  3301.         .o, Insert specified object into destination library (raw copy)
  3302.  
  3303.         .lib, Insert specified library into destination library (raw copy)
  3304.  
  3305.         other, Assumed to be a C source file to compile with DCC
  3306.  
  3307.           SEE ALSO
  3308.         lbmake
  3309.  
  3310.  
  3311. dice/libtos                                                      dice/libtos
  3312.  
  3313.     NAME
  3314.         Library Converter
  3315.  
  3316.     SYNOPSIS
  3317.         LIBTOS source dest
  3318.  
  3319.     DESCRIPTION
  3320.         This program converts the Commodore supplied amiga.lib from large data
  3321.         model to small data model.  You must convert amiga.lib before you can
  3322.         use it with the DICE system to generate residentable programs.
  3323.  
  3324.         Note that this isn't required, but a small-data amiga.lib will
  3325.         generate faster code with fewer reloc32's (and thus load much faster).
  3326.  
  3327.         The small-data-model version of amiga.lib is called amigas.lib
  3328.  
  3329.         1> cd DLIB:
  3330.         1> LIBTOS amiga.lib amigas.lib
  3331.  
  3332.  
  3333. dice/loadabs                                                    dice/loadabs
  3334.  
  3335.     NAME
  3336.         Absolute Locator
  3337.  
  3338.     SYNOPSIS
  3339.         LoadAbs exefile -o outfile -A addr
  3340.  
  3341.     DESCRIPTION
  3342.         LoadAbs takes a standard Amiga executable and generates an image file
  3343.         relocated to the absolute location specified.  The image file is layed
  3344.         out in the same order as the hunks appear in the Amiga executable. 
  3345.         BSS hunks will generate 0's in the image file.
  3346.  
  3347.    exefile  Executable to do the absolute relocation on
  3348.  
  3349.  -O outfile
  3350.             Resulting image file
  3351.  
  3352.    -A addr  - 0xHEX absolute relocation address
  3353.  
  3354.             :: NOTE: This program will do 32 bit relocations only.  Generally
  3355.             :: you only use LoadAbs with -mD -mC compiled programs.
  3356.  
  3357.  
  3358. dice/makeproto                                                dice/makeproto
  3359.  
  3360.     NAME
  3361.         Create Prototype File
  3362.  
  3363.     SYNOPSIS
  3364.         makeproto infile outfile
  3365.  
  3366.     DESCRIPTION
  3367.         header file from source files
  3368.  
  3369.     infile  input file
  3370.  
  3371.    outfile  output file
  3372.  
  3373.  
  3374. dice/merge                                                        dice/merge
  3375.  
  3376.     NAME
  3377.         Three-Way File Merge
  3378.  
  3379.     SYNOPSIS
  3380.         merge
  3381.  
  3382.     DESCRIPTION
  3383.         Merge does a three way file merge
  3384.  
  3385.     SEE ALSO
  3386.         rcsmerge
  3387.  
  3388.  
  3389. dice/rcs                                                            dice/rcs
  3390.  
  3391.     NAME
  3392.         Change RCS File Attributes
  3393.  
  3394.     SYNOPSIS
  3395.         rcs [ options ] file ...
  3396.  
  3397.     DESCRIPTION
  3398.         Rcs creates new RCS files or changes attributes of existing ones.  An
  3399.         RCS file contains multiple revisions of text, an access list, a change
  3400.         log, descriptive text, and some control attributes.  For rcs to work,
  3401.         the caller's login name must be on the access list, except if the
  3402.         access list is empty, the caller is the owner of the file or the
  3403.         superuser, or the -i option is present.
  3404.  
  3405.         Files ending in `,v' are RCS files, all others are working files.  If
  3406.         a working file is given, rcs tries to find the corresponding RCS file
  3407.         first in directory ./RCS and then in the current directory, as
  3408.         explained in co.
  3409.  
  3410.         -i  creates and initializes a new RCS file, but does not deposit any
  3411.             revision.  If the RCS file has no path prefix, rcs tries to place
  3412.             it first into the subdirectory ./RCS, and then into the current
  3413.             directory.  If the RCS file already exists, an error message is
  3414.             printed.
  3415.  
  3416.   -alogins  appends the login names appearing in the comma-separated list
  3417.             logins to the access list of the RCS file.
  3418.  
  3419.  -Aoldfile  appends the access list of oldfile to the access list of the RCS
  3420.             file.
  3421.  
  3422.  -e[logins]
  3423.             erases the login names appearing in the comma-separated list
  3424.             logins from the access list of the RCS file.  If logins is
  3425.             omitted, the entire access list is erased.
  3426.  
  3427.    -b[rev]  sets the default branch to rev.  If rev is omitted, the default
  3428.             branch is reset to the (dynamically) highest branch on the trunk.
  3429.  
  3430.   -cstring  sets the comment leader to string.  The comment leader is printed
  3431.             before every log message line generated by the keyword
  3432.             $Log: chap08.doc,v $
  3433. # Revision 30.8  1994/08/18  05:37:03  dice
  3434. # .
  3435. #
  3436. # Revision 30.0  1994/06/10  17:54:37  dice
  3437. # .
  3438. #
  3439. # Revision 30.0  1994/06/10  17:54:37  dice
  3440. # .
  3441. # Revision 1.2  92/06/09  06:40:43  jtoebes
  3442.             Incorporate new das, enforcer examples from Bryce.  Fix up dprof
  3443.             example section.
  3444.  
  3445.             Revision 1.1  92/06/01  23:01:29  jtoebes Initial revision  during
  3446.             checkout (see co).  This is useful for programming languages
  3447.             without multi-line comments.  During rcs -i or initial ci, the
  3448.             comment leader is guessed from the suffix of the working file.
  3449.  
  3450.    -l[rev]  locks the revision with number rev.  If a branch is given, the
  3451.             latest revision on that branch is locked.  If rev is omitted, the
  3452.             latest revision on the default branch is locked.  Locking prevents
  3453.             overlapping changes.  A lock is removed with ci or rcs -u (see
  3454.             below).
  3455.  
  3456.    -u[rev]  unlocks the revision with number rev.  If a branch is given, the
  3457.             latest revision on that branch is unlocked.  If rev is omitted,
  3458.             the latest lock held by the caller is removed.  Normally, only the
  3459.             locker of a revision may unlock it.  Somebody else unlocking a
  3460.             revision breaks the lock.
  3461.  
  3462.         -L  Sets locking to strict.  Strict locking means that the owner of an
  3463.             RCS file is not exempt from locking for checkin.  This option
  3464.             should be used for files that are shared.
  3465.  
  3466.         -U  Sets locking to non-strict.  Non-strict locking means that the
  3467.             owner of a file need not lock a revision for checkin.  This option
  3468.             should NOT be used for files that are shared.
  3469.  
  3470.  -nname[:rev]
  3471.             Associates the symbolic name name with the branch or revision rev.
  3472.             Rcs prints an error message if name is already associated with
  3473.             another number. If rev is omitted, the symbolic name is deleted.
  3474.  
  3475.  -Nname[:rev]
  3476.             Same as -n, except that it overrides a previous assignment of
  3477.             name.
  3478.  
  3479.    -orange  Deletes ("outdates") the revisions given by range.  A range
  3480.             consisting of a single revision number means that revision.  A
  3481.             range consisting of a branch number means the latest revision on
  3482.             that branch.  A range of the form rev1-rev2 means revisions rev1
  3483.             to rev2 on the same branch, -rev means from the beginning of the
  3484.             branch containing rev up to and including rev, and rev means from
  3485.             revision rev to the end of the branch containing rev.  None of the
  3486.             outdated revisions may have branches or locks.
  3487.  
  3488.         -q  Quiet mode; diagnostics are not printed.
  3489.  
  3490.  -sstate[:rev]
  3491.             sets the state attribute of the revision rev to state.  If rev is
  3492.             a branch number, the latest revision on that branch is assumed. 
  3493.             If rev is omitted, the latest revision on the default branch is
  3494.             assumed.  Any identifier is acceptable for state.  A useful set of
  3495.             states is Exp (for experimental), Stab (for stable), and Rel (for
  3496.             released).  By default, ci sets the state of a revision to Exp.
  3497.  
  3498.  -t[txtfile]
  3499.             writes descriptive text into the RCS file (deletes the existing
  3500.             text).  If txtfile is omitted, rcs prompts the user for text
  3501.             supplied from the standard input, terminated with a line
  3502.             containing a single `.' or control-\.  Otherwise, the descriptive
  3503.             text is copied from the file txtfile.  If the -i option is
  3504.             present, descriptive text is requested even if -t is not given. 
  3505.             The prompt is suppressed if the standard input is not a terminal.
  3506.  
  3507.     DIAGNOSTICS
  3508.         The RCS file name and the revisions outdated are written to the
  3509.         diagnostic output.  The exit status always refers to the last RCS file
  3510.         operated upon, and is 0 if the operation was successful, 1 otherwise.
  3511.  
  3512.     FILES
  3513.         Rcs creates a semaphore file in the same directory as the RCS file to
  3514.         prevent simultaneous update.  For changes, rcs always creates a new
  3515.         file.  On successful completion, rcs deletes the old one and renames
  3516.         the new one.
  3517.  
  3518.     SEE ALSO
  3519.         co, ci, ident, rcsdiff, rcsintro, rcsmerge, rlog
  3520.  
  3521.  
  3522. dice/rcsclean                                                  dice/rcsclean
  3523.  
  3524.     NAME
  3525.         Clean up RCS Work Files
  3526.  
  3527.     SYNOPSIS
  3528.         rcsclean [ -rrev ] [ -qrev ] file...
  3529.  
  3530.     DESCRIPTION
  3531.         Rcsclean removes working files that were checked out and never
  3532.         modified.  For each file given, rcsclean compares the working file and
  3533.         a revision in the corresponding RCS file.  If it finds no difference,
  3534.         it removes the working file, and, if the revision was locked by the
  3535.         caller, unlocks the revision.
  3536.  
  3537.         A file name ending in ',v' is an RCS file name, otherwise a working
  3538.         file name.  Rcsclean derives the working file name from the RCS file
  3539.         name and vice versa, as explained in co.  Pairs consisting of both an
  3540.         RCS and a working file name may also be specified.
  3541.  
  3542.        Rev  specifies with which revision the working file is compared.  If
  3543.             rev is omitted, rcsclean compares the working file with the latest
  3544.             revision on the default branch (normally the highest branch on the
  3545.             trunk).
  3546.  
  3547.         -q  suppresses diagnostics.
  3548.  
  3549.             Rcsclean is useful for "clean" targets in Makefiles.  Note that
  3550.             rcsdiff prints out the differences.  Also, ci normally asks
  3551.             whether to check in a file if it was not changed.
  3552.  
  3553.     EXAMPLES
  3554.         The command
  3555.  
  3556.         rcsclean *.c *.h
  3557.  
  3558.         removes all working files ending in ".c" or ".h" that were not changed
  3559.         since their checkout.
  3560.  
  3561.     DIAGNOSTICS
  3562.         The exit status is 0 if there were no differences during the last
  3563.         comparison or if the last working file did not exist, 1 if there were
  3564.         differences, and 2 if there were errors.
  3565.  
  3566.     SEE ALSO
  3567.         co, ci, ident, rcs, rcsdiff, rcsintro, rcsmerge, rlog, .
  3568.  
  3569.  
  3570. dice/rcsdiff                                                    dice/rcsdiff
  3571.  
  3572.     NAME
  3573.         Compare RCS Revisions
  3574.  
  3575.     SYNOPSIS
  3576.         rcsdiff [ -biwt ] [ -cefhn ] [ -q ] [ -rrev1 ] [ -rrev2 ] file ...
  3577.  
  3578.     DESCRIPTION
  3579.         Rcsdiff runs diff to compare two revisions of each RCS file given.  A
  3580.         file name ending in ',v' is an RCS file name, otherwise a working file
  3581.         name.  Rcsdiff derives the working file name from the RCS file name
  3582.         and vice versa, as explained in co.  Pairs consisting of both an RCS
  3583.         and a working file name may also be specified.
  3584.  
  3585.         The options -b, -i, -w, -t, -c, -e, -f, and -h, have the same effect
  3586.         as described in diff.
  3587.  
  3588.         -n  generates an edit script of the format used by RCS
  3589.  
  3590.         -q  Suppresses diagnostic output.
  3591.  
  3592.             If both rev1 and rev2 are omitted, rcsdiff compares the latest
  3593.             revision on the default branch (normally the highest branch on the
  3594.             trunk) with the contents of the corresponding working file.  This
  3595.             is useful for determining what you changed since the last checkin.
  3596.  
  3597.             If rev1 is given, but rev2 is omitted, rcsdiff compares revision
  3598.             rev1 of the RCS file with the contents of the corresponding
  3599.             working file.
  3600.  
  3601.             If both rev1 and rev2 are given, rcsdiff compares revisions rev1
  3602.             and rev2 of the RCS file.
  3603.  
  3604.             Both rev1 and rev2 may be given numerically or symbolically, and
  3605.             may actually be attached to any of the options.
  3606.  
  3607.     EXAMPLES
  3608.         The command
  3609.  
  3610.         rcsdiff f.c
  3611.  
  3612.         runs diff on the latest revision on the default branch of RCS file
  3613.         f.c,v and the contents of working file f.c.
  3614.  
  3615.     DIAGNOSTICS
  3616.         The exit status is 0 if there were no differences during the last
  3617.         comparison, 1 if there were differences, and 2 if there were errors.
  3618.  
  3619.     SEE ALSO
  3620.         ci, co, diff, ident, rcs, rcsintro, rcsmerge, rlog
  3621.  
  3622.  
  3623. dice/rcsmerge                                                  dice/rcsmerge
  3624.  
  3625.     NAME
  3626.         Merge RCS Revisions
  3627.  
  3628.     SYNOPSIS
  3629.         rcsmerge -rrev1 [ -rrev2 ] [ -p ] file
  3630.  
  3631.     DESCRIPTION
  3632.         Rcsmerge incorporates the changes between rev1 and rev2 of an RCS file
  3633.         into the corresponding working file.  If -p is given, the result is
  3634.         printed on the standard output, otherwise the result overwrites the
  3635.         working file.
  3636.  
  3637.         A file name ending in ',v' is an RCS file name, otherwise a working
  3638.         file name.  Rcsmerge derives the working file name from the RCS file
  3639.         name and vice versa, as explained in co.  A pair consisting of both an
  3640.         RCS and a working file name may also be specified.
  3641.  
  3642.         Rev1 may not be omitted.  If rev2 is omitted, the latest revision on
  3643.         the default branch (normally the highest branch on the trunk) is
  3644.         assumed.  Both rev1 and rev2 may be given numerically or symbolically.
  3645.  
  3646.         Rcsmerge prints a warning if there are overlaps, and delimits the
  3647.         overlapping regions as explained in co -j.  The command is useful for
  3648.         incorporating changes into a checked-out revision.
  3649.  
  3650.     EXAMPLES
  3651.         Suppose you have released revision 2.8 of f.c.  Assume furthermore
  3652.         that you just completed revision 3.4, when you receive updates to
  3653.         release 2.8 from someone else.  To combine the updates to 2.8 and your
  3654.         changes between 2.8 and 3.4, put the updates to 2.8 into file f.c and
  3655.         execute
  3656.  
  3657.         rcsmerge -p -r2.8 -r3.4 f.c >f.merged.c
  3658.  
  3659.         Then examine f.merged.c.  Alternatively, if you want to save the
  3660.         updates to 2.8 in the RCS file, check them in as revision 2.8.1.1 and
  3661.         execute co -j:
  3662.  
  3663.         ci -r2.8.1.1 f.c
  3664.         co -r3.4 -j2.8:2.8.1.1 f.c
  3665.  
  3666.         As another example, the following command undoes the changes between
  3667.         revision 2.4 and 2.8 in your currently checked out revision in f.c.
  3668.  
  3669.         rcsmerge -r2.8 -r2.4 f.c
  3670.  
  3671.         Note the order of the arguments, and that f.c will be overwritten.
  3672.  
  3673.     SEE ALSO
  3674.         ci, co, merge, ident, rcs, rcsdiff, rlog
  3675.  
  3676.     BUGS
  3677.         Rcsmerge does not work on files that contain lines with a single `.'.
  3678.  
  3679.  
  3680. dice/rlog                                                          dice/rlog
  3681.  
  3682.     NAME
  3683.         Display RCS History
  3684.  
  3685.     SYNOPSIS
  3686.         rlog [ options ] file ...
  3687.  
  3688.     DESCRIPTION
  3689.         Rlog prints information about RCS files.  Files ending in `,v' are RCS
  3690.         files, all others are working files.  If a working file is given, rlog
  3691.         will locate the corresponding RCS file.
  3692.  
  3693.         Rlog prints the following information for each RCS file: RCS file
  3694.         name, working file name, head (i.e., the number of the latest revision
  3695.         on the trunk), default branch, access list, locks, symbolic names,
  3696.         suffix, total number of revisions, number of revisions selected for
  3697.         printing, and descriptive text.  This is followed by entries for the
  3698.         selected revisions in reverse chronological order for each branch. 
  3699.         For each revision, rlog prints revision number, author, date/time,
  3700.         state, number of lines added/deleted (with respect to the previous
  3701.         revision), locker of the revision (if any), and log message.  Without
  3702.         options, rlog prints complete information.  The options below restrict
  3703.         this output.
  3704.  
  3705.         -L  ignores RCS files that have no locks set; convenient in
  3706.             combination with -R, -h, or -l.
  3707.  
  3708.         -R  only prints the name of the RCS file; convenient for translating a
  3709.             working file name into an RCS file name.
  3710.  
  3711.         -h  prints only RCS file name, working file name, head, default
  3712.             branch, access list, locks, symbolic names, and suffix.
  3713.  
  3714.         -t  prints the same as -h, plus the descriptive text.
  3715.  
  3716.         -b  prints information about the revisions on the default branch
  3717.             (normally the highest branch on the trunk).
  3718.  
  3719.    -ddates  prints information about revisions with a checkin date/time in the
  3720.             ranges given by the semicolon- separated list of dates.  A range
  3721.             of the form d1<MIXd2 or d2>d1 selects the revisions that were
  3722.             deposited between d1 and d2, (inclusive).  A range of the form
  3723.             <MIXd or d> selects all revisions dated d or earlier.  A range of
  3724.             the form d<D or >d selects all revisions dated d or later.  A
  3725.             range of the form d selects the single, latest revision dated d or
  3726.             earlier.  The date/time strings d, d1, and d2 are in the free
  3727.             format explained in co.  Quoting is normally necessary, especially
  3728.             for <D and >.  Note that the separator is a semicolon.
  3729.  
  3730.  -l[lockers]
  3731.             prints information about locked revisions.  If the comma-separated
  3732.             list lockers of login names is given, only the revisions locked by
  3733.             the given login names are printed.  If the list is omitted, all
  3734.             locked revisions are printed.
  3735.  
  3736.  -rrevisions
  3737.             prints information about revisions given in the comma-separated
  3738.             list revisions of revisions and ranges.  A range rev1-rev2 means
  3739.             revisions rev1 to rev2 on the same branch, -rev means revisions
  3740.             from the beginning of the branch up to and including rev, and rev-
  3741.             means revisions starting with rev to the end of the branch
  3742.             containing rev.  An argument that is a branch means all revisions
  3743.             on that branch.  A range of branches means all revisions on the
  3744.             branches in that range.
  3745.  
  3746.   -sstates  prints information about revisions whose state attributes match
  3747.             one of the states given in the comma-separated list states.
  3748.  
  3749.  -w[logins]
  3750.             prints information about revisions checked in by users with login
  3751.             names appearing in the comma- separated list logins.  If logins is
  3752.             omitted, the user's login is assumed.
  3753.  
  3754.             Rlog prints the intersection of the revisions selected with the
  3755.             options -d, -l, -s, -w, intersected with the union of the
  3756.             revisions selected by -b and -r.
  3757.  
  3758.     EXAMPLES
  3759.         rlog -L -R RCS/*,v
  3760.         rlog -L -h RCS/*,v
  3761.         rlog -L -l RCS/*,v
  3762.         rlog RCS/*,v
  3763.  
  3764.         The first command prints the names of all RCS files in the
  3765.         subdirectory `RCS' which have locks.  The second command prints the
  3766.         headers of those files, and the third prints the headers plus the log
  3767.         messages of the locked revisions.  The last command prints complete
  3768.         information.
  3769.  
  3770.     DIAGNOSTICS
  3771.         The exit status always refers to the last RCS file operated upon, and
  3772.         is 0 if the operation was successful, 1 otherwise.
  3773.  
  3774.     SEE ALSO
  3775.         ci, co, ident, rcs, rcsdiff, rcsintro, rcsmerge,
  3776.  
  3777.  
  3778. dice/romable                                                    dice/romable
  3779.  
  3780.     NAME
  3781.         Generate Romable Image
  3782.  
  3783.     SYNOPSIS
  3784.         Romable exeFile -o outFile [-o outFile2] -C addr -D addr  -pi
  3785.  
  3786.     DESCRIPTION
  3787.         Romable generates a binary image for an executable compiled under DICE
  3788.         and is normally used to generate a ROMABLE raw binary output file.
  3789.  
  3790.    exeFile  input executable linked with dlink
  3791.  
  3792.  -o outFile
  3793.             output binary (unformatted -- raw).  If TWO -o options are
  3794.             specified the two output files will have even bytes and odd bytes
  3795.             respectively, which is what you need when you must program two
  3796.             eproms (one on the LSB data lines and one on the MSB data lines)
  3797.  
  3798.             example:
  3799.  
  3800.             -o out1
  3801.  
  3802.             result: 01 02 03 04
  3803.  
  3804.             example:
  3805.  
  3806.             -o out1 -o out2
  3807.  
  3808.             result
  3809.  
  3810.             (out1): 01 03 result (out2): 02 04
  3811.  
  3812.    -C addr  code start address, 0octal, decimal, or 0xHEX
  3813.  
  3814.    -D addr  data start address, 0octal, decimal, or 0xHEX
  3815.  
  3816.        -DC  place actual data+bss just after code (i.e.  the result is
  3817.             intended to be downloaded into RAM, there is no duplicate data in
  3818.             this case).
  3819.  
  3820.             '-D addr' is not specified in this case
  3821.  
  3822.        -pi  generate a position independant module.  Neither -C or -D are
  3823.             specified in this case, and Romable will warn you have any
  3824.             absolute references.
  3825.  
  3826.             Note that your custom startup code determines how much of
  3827.             __autoinit and __autoexit is to be supported.  Note especially
  3828.             that __autoinit0 MUST BE SUPPORTED because DICE will generate
  3829.             __autoinit0 sections to handle 32 bit data relocations run-time.
  3830.  
  3831.             Romable generates a raw output file or files with the EPROM code
  3832.             first, and initialized data after the main code (still in EPROM)
  3833.             which, as has already been described, will be copied to RAM on
  3834.             reset by your startup routine.
  3835.  
  3836.             This startup-copying of initialized data and clearing of BSS makes
  3837.             it extremely easy to use DICE to generate ROMED applications
  3838.             without having to deal with major porting considerations.
  3839.  
  3840.  
  3841. dice/touch                                                        dice/touch
  3842.  
  3843.     NAME
  3844.         Update File Datestamp
  3845.  
  3846.     SYNOPSIS
  3847.         touch file
  3848.  
  3849.     DESCRIPTION
  3850.         Touch sets the date of a file
  3851.  
  3852.         SEE ALSO
  3853.         dmake
  3854.  
  3855.         @MAJOR HEADING = wc
  3856.  
  3857.     NAME
  3858.         Count Elements in a file
  3859.  
  3860.     SYNOPSIS
  3861.         wc file ...
  3862.  
  3863.     DESCRIPTION
  3864.         Wordcount is useful for...
  3865.  
  3866.     SEE ALSO
  3867.